Gemini image API

Available in the Official and Discount groups. Use a key from the chosen group. Both groups use the same public model IDs; use them exactly as listed, without adding suffixes or a group field.

Supported protocol

Generate with JSON POST /v1/images/generations, or upload files with POST /v1/images/edits (multipart/form-data). Submission returns 202 Accepted and a task id. Poll GET /v1/tasks/{id} until completed or failed. A 202 response is not a completed image.

This family uses Images + asynchronous tasks. Image generation through /v1/chat/completions or /v1/responses is not supported. See the complete submission and polling example.

Models and parameters

size is the aspect ratio, such as 1:1 or 16:9; resolution is the resolution tier and defaults to 1K. Prompts are limited to 1000 characters for 2.5 and 4000 for the other two models. Generate one image per request: use n: 1 or omit it.

Generate an image

Set APIPOOL_API_KEY to your key, then run:

APIPOOL_ENDPOINT="https://app.apipool.dev"

curl "$APIPOOL_ENDPOINT/v1/images/generations" \
  -H "Authorization: Bearer $APIPOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A blue ceramic cup on a white table",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
}'

Edit an image

Upload a local PNG, JPEG or WebP file, replacing source.png with its path:

curl "https://app.apipool.dev/v1/images/edits" \
  -H "Authorization: Bearer $APIPOOL_API_KEY" \
  -F "model=gemini-3.1-flash-image-preview" \
  -F "prompt=Change the cup to green" \
  -F "image=@./source.png" \
  -F "size=1:1" \
  -F "resolution=1K" \
  -F "n=1"

For multiple references, repeat -F "image=@./second.png" within the model's limit. To use publicly downloadable references, send image_urls to the same JSON generation endpoint:

{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "Change the cup to green",
  "size": "1:1",
  "resolution": "1K",
  "n": 1,
  "image_urls": ["https://your-cdn.example/source.png"]
}

Replace the example URL with a real address reachable by the server. Expired tunnels, DNS failures and download timeouts can fail the task. Browser-only localhost or authenticated image URLs are unsuitable.

Poll and retrieve results

Save the submission's id, such as imgtask_01..., and query with the same key:

TASK_ID="imgtask_01..."
curl "https://app.apipool.dev/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $APIPOOL_API_KEY"

Continue polling for submitted, submission_unknown, processing or meter_pending. On completed, read data[].url and download before expiry. On failed, inspect error. Do not resubmit while waiting. See Asynchronous image tasks for all states, timeout handling and a runnable polling example.

Scope and billing

Google native image generation uses a different protocol. These standalone image models use the Images task API on APIPool; native Gemini endpoints and Chat Completions / Responses image-generation compatibility are not offered for these listings.

See the selected model and group in Models & pricing. Pricing and available parameter tiers depend on that listing.