GPT Image 2

POST https://api.beatapi.io/v1/images/tasks

Generate or edit images from text and up to sixteen public HTTPS reference images, with output up to 4K.

Supported modes

Async flow: Create the task, save data.id, then poll the Task with GET /v1/tasks/{task_id}. On succeeded, read data.output.media. On failed, read data.error_code and data.error_message, then follow the error and retry policy.

Using a local file? upload a local input first and pass the returned data.url.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

model   string   required

Must be gpt-image-2.

Value: gpt-image-2

prompt   string   required

Generation or image-editing instructions.

Length: 1 to 5000 characters

images   string[]   optional

Public HTTPS reference-image URLs. Omit for text-to-image.

Count: 1 to 16 items

aspect_ratio   enum<string>   optional

Output image aspect ratio.

Available options: auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9, 9:21
Default: "auto"

resolution   enum<string>   optional

Output resolution tier.

Available options: 1K, 2K, 4K
Default: "1K"

Request examples

Text to image

$
curl --request POST \
>
  --url https://api.beatapi.io/v1/images/tasks \
>
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
  "model": "gpt-image-2",
>
  "prompt": "A clean campaign image with soft studio lighting.",
>
  "aspect_ratio": "1:1",
>
  "resolution": "1K"
>
}'

Reference image

$
curl --request POST \
>
  --url https://api.beatapi.io/v1/images/tasks \
>
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
  "model": "gpt-image-2",
>
  "prompt": "Create a clean campaign image from the supplied product reference.",
>
  "images": [
>
    "https://media.beatapi.io/samples/smart-bottle.png"
>
  ],
>
  "aspect_ratio": "1:1",
>
  "resolution": "2K"
>
}'

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "task_8K2qA",
4
    "object": "task",
5
    "task_kind": "image",
6
    "capability_id": "gpt-image-2",
7
    "capability_version": null,
8
    "media_type": "image",
9
    "model": "gpt-image-2",
10
    "status": "queued",
11
    "stage": "queued",
12
    "created_at": 1782210000,
13
    "updated_at": 1782210000,
14
    "completed_at": null,
15
    "output": null,
16
    "usage": {
17
      "credits_reserved": 0.04,
18
      "credits_charged": 0.04,
19
      "credits_settled": 0,
20
      "credits_refunded": 0
21
    },
22
    "request_id": "req_abc123",
23
    "error_code": null,
24
    "error_message": null
25
  }
26
}

Errors