Image API

Create one asynchronous image generation task with a stable BeatAPI model ID.

Model	Input modes	Required fields	Main controls
`nano-banana`	Text, reference images	`model`, `prompt`	Up to 10 references, aspect ratio, PNG/JPEG output
`nano-banana-2`	Text, reference images	`model`, `prompt`	Up to 10 references, 1K/2K/4K, PNG/JPEG output
`nano-banana-2-lite`	Text, reference images	`model`, `prompt`	Up to 10 references, fixed 1K, PNG/JPEG output
`nano-banana-pro`	Text, reference images	`model`, `prompt`	Up to 8 references, up to 4K
`gpt-image-2`	Text, reference images	`model`, `prompt`	Up to 16 references, broad aspect ratios, up to 4K
`seedream-5-pro`	Text, reference images	`model`, `prompt`	Up to 10 references, 1K/2K/4K
`grok-imagine-image-2.0`	Text, reference images	`model`, `prompt`	Up to 5 references, automatic edit-mode selection

Open the matching model page for every field, default, enum, combination rule, request example, response, and error behavior.

List available models

GET /v1/media/models

Parameter	Location	Type	Required	Allowed values
`media_type`	Query	string	No	`image`, `video`

This public endpoint does not require authentication.

$ curl "https://api.beatapi.io/v1/media/models?media_type=image"

1 {
2   "data": {
3     "object": "list",
4     "data": [
5       {
6         "id": "gpt-image-2",
7         "object": "generation_model",
8         "name": "GPT Image 2",
9         "media_type": "image",
10         "input_modes": ["text", "image"]
11       }
12     ]
13   }
14 }

Field	Type	Meaning
`id`	string	Stable public model alias
`object`	string	`generation_model`
`name`	string	Display name
`media_type`	string	`image` or `video`
`input_modes`	string[]	Any of `text`, `image`, `frames`, `reference`

Internal provider routing is not part of the public contract.

Shared create contract

POST /v1/images/tasks

Header	Type	Required	Rules
`Authorization`	string	Yes	`Bearer <BEATAPI_API_KEY>`
`Content-Type`	string	Yes	`application/json`
`Idempotency-Key`	string	No, recommended	Up to 255 characters; one key per logical create

The body must match exactly one model schema. model is the discriminator; unknown fields are rejected.

$ curl https://api.beatapi.io/v1/images/tasks \
>   -X POST \
>   -H "Authorization: Bearer $BEATAPI_API_KEY" \
>   -H "Idempotency-Key: image-gpt-image-2-001" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-image-2",
>     "prompt": "Editorial product photograph on a warm stone pedestal.",
>     "aspect_ratio": "1:1",
>     "resolution": "1K"
>   }'

A valid request returns 201 Created with data.id, task_kind="image", the selected model, status="queued", usage metrics, and request_id. Poll GET /v1/tasks/{task_id} every 5–10 seconds until succeeded or failed; successful image is in data.output.media[] and data.output.r2_url.

An exact idempotent replay returns the accepted task. Reusing a key with a different body returns 409 idempotency_conflict.

Shared errors

HTTP	Common code	Client action
`400`	`bad_request`	Fix fields, values, combinations, counts, or media URLs
`401`	`unauthorized`	Check the Bearer key
`402`	`insufficient_credits`	Add credits before creating a new task
`409`	`idempotency_conflict`	Reuse the key only with the exact same body
`429`	Rate or concurrency code	Honor the retry delay or wait for active work to finish

Error responses include error.code, error.message, error.request_id, and optional error.retry_after_seconds. The per-model pages below are the production request contracts.