Stable, asynchronous, and decoupled from execution nodes.

Every request uses a stable logical model. Public responses never include routing details, internal job IDs, endpoints, or credentials.

Quick start

Create an API key in the console, submit a job, then use the returned job_id to look it up. Only successful jobs are charged to the account balance.

curl https://gateway.example.com/v1/images/generations \
  -H "Authorization: Bearer sk-gw-your-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-asset-2026-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Minimal product photo, soft daylight",
    "image_urls": [],
    "aspect_ratio": "1:1",
    "resolution": "2k"
  }'

Authentication

Every v1 endpoint uses a Bearer key.

Authorization: Bearer sk-gw-...

Never put an API key in public browser code or a Git repository. One account can create multiple keys with independent limits.

POST/v1/images/generations

Create image job

Field	Type	Notes
`model`	string	gpt-image-2 or a listed Nano Banana model; call GET /v1/models for the active catalog
`prompt`	string	Required, up to 20,000 characters
`image_urls`	string[]	Optional; any image URL uses the model's edit operation. Limits are model-specific (up to 14).
`aspect_ratio`	enum	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 / auto
`resolution`	enum	1k / 2k / 4k · model-specific
`idempotency_key`	string	May be sent in the body or the Idempotency-Key header

Response

{
  "object": "generation.job",
  "job_id": "job_...",
  "model": "gpt-image-2",
  "status": "running",
  "artifacts": [],
  "error": null,
  "price": {
    "amount_micros": 50000,
    "amount": "0.050000",
    "currency": "usd"
  }
}

POST/v1/videos/generations

Create video job

Seedance 2.0 is priced dynamically by resolution and duration. The first image_urls item is the first frame and the second is the last frame; without images it is text-to-video.

Field	Type	Notes
`model`	string	Fixed to seedance-2
`prompt`	string	Required, up to 20,000 characters
`image_urls`	string[]	Optional, at most two first/last frames
`aspect_ratio`	enum	16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9
`resolution`	enum	480p / 720p / 1080p
`duration`	integer	5–15 seconds
`generate_audio`	boolean	Whether to generate audio too; true by default

curl https://gateway.example.com/v1/videos/generations \
  -H "Authorization: Bearer sk-gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2",
    "prompt": "A paper boat crossing a neon-lit rainy street",
    "image_urls": [],
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  }'

GET/v1/jobs/:job_id

Query job

The public status is limited to queued, running, succeeded, and failed. After success, artifacts contains image or video URLs; polling stops when the job reaches a terminal state.

curl https://gateway.example.com/v1/jobs/job_... \
  -H "Authorization: Bearer sk-gw-your-key"

GET/v1/models

Models

Returns active logical models, capabilities, and minimum–maximum price ranges without exposing their execution-node mapping. Successful jobs settle at the price of the route actually used.

Error codes

invalid_requestunauthorizedaccount_unavailablekey_limit_exceededinsufficient_balancemodel_unavailableprovider_unavailablegeneration_failedtask_timeoutinternal_error