Gemini image — HopsAPI Docs

The models below are media models. Create a task with POST /v1/router/task/create and poll GET /v1/router/tasks/{task_id}. nano-banana-pro and nano-banana-2 have their own pages and model IDs.

Call GET /v1/models first and use a model ID that the current API key can see.

Models

Standard prices are USD / 1M tokens: input, text plus thinking output, then image output. The account charge also applies platform settlement and the price coefficient. The aspect ratios, resolutions, and prices in the table follow GET /v1/models and the price page.

Model ID	Aspect ratios	Resolution	Standard price
`gemini-3-pro-image`	`1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9`	`1K` `2K`	$2 / $12 / $120
`gemini-3.1-flash-image`	`1:1` `1:4` `1:8` `2:3` `3:2` `3:4` `4:1` `4:3` `4:5` `5:4` `8:1` `9:16` `16:9` `21:9`	`1K` `2K`	$0.50 / $3 / $60
`gemini-3.1-flash-lite-image`	`1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9`	`1K`	$0.25 / $1.50 / $30
`gemini-nano-banana-2.1`	`1:1` `1:4` `1:8` `2:3` `3:2` `3:4` `4:1` `4:3` `4:5` `5:4` `8:1` `9:16` `16:9` `21:9`	`1K` `2K` `4K`	$1.50 / $7.50 / $30

Resolution matching is case-insensitive. 1k is sent as the configured 1K. Any other aspect ratio or resolution returns HTTP 400 and does not create a task.

Task flow

For image-to-image, prepare a public HTTPS image. Upload a local file, Base64 payload, or Data URL through HopsAPI file upload and use the public fileUrl.
Send task, model, and input to POST /v1/router/task/create. The response returns a tsk_* task_id immediately. These models do not reserve a balance.
Poll GET /v1/router/tasks/{task_id} every 3–5 seconds until the task is terminal. A task for these models cannot be cancelled after it is submitted. An API key can only read tasks created by the same buyer.
At status 2, read results[].urls and cost, then download the image. Result URLs expire.

Status	Meaning
`0`	Queued
`1`	Processing
`2`	Completed. `results[].urls` holds the image and `cost` is credits
`3`	Failed. No charge is settled

A failure is the neutral Provider error (request id: aitk-...). The raw upstream body is not included.

Request fields

Field	Type	Required	Description
`task`	string	Yes	`Txt2Img` or `Img2Img`
`model`	string	Yes	A model ID from the table above
`input.prompt`	string	Yes	Non-empty prompt
`input.aspect_ratio`	string	Yes	An aspect ratio that model allows, matched exactly
`input.resolution`	string	Yes	A resolution that model allows
`input.images`	string[]	Required for Img2Img	1–14 public HTTPS image URLs. An `http://` URL returns HTTP `400`
`input.output_format`	string	No	Omit it, or send `png`. `jpg` returns HTTP `400`
`mode`	string	No	Leave it unset. A non-empty value returns HTTP `400`
`callback_url`	string	No	Optional public HTTPS webhook. See Media task callbacks.

Billing

A successful task is billed on three meters: input tokens at the input price, text and thinking tokens at the text output price, and image tokens at the image output price. When the output cannot be split, the whole output is billed at the image output price. Official USD converts at $1 = 100 credits, then platform settlement, reseller pricing, and the account coefficient apply.

cost in the task query is the credit charge for that call. The public response does not include token counts. A failed task is not charged.

Examples

# Text to image
curl https://hopsapi.com/v1/router/task/create \
  -H "Authorization: Bearer sk-YOUR_KEY" -H "content-type: application/json" \
  -d '{"task":"Txt2Img","model":"gemini-3.1-flash-image",
       "input":{"prompt":"a small cat","aspect_ratio":"1:1","resolution":"1K"}}'

# Image to image
curl https://hopsapi.com/v1/router/task/create \
  -H "Authorization: Bearer sk-YOUR_KEY" -H "content-type: application/json" \
  -d '{"task":"Img2Img","model":"gemini-3-pro-image",
       "input":{"prompt":"put a red hat on the cat","aspect_ratio":"1:1","resolution":"1K",
                "images":["https://example.com/cat.png"]}}'

Responses

Create:

{
  "code": 200,
  "message": "success",
  "task_id": "tsk_mabc1234_0123456789abcdef01234567"
}

After the image is stored and the charge is settled:

{
  "task_id": "tsk_mabc1234_0123456789abcdef01234567",
  "status": 2,
  "results": [{ "urls": ["https://assets.example.com/gemini-image-1.png"] }],
  "cost": 6.72
}

A failed task has status 3, no cost, and a message such as Provider error (request id: aitk-...).