Getting Started

This guide shows the minimum flow for creating a generation task and retrieving the result.

1. Create an API key

Open the API Keys page, then click Create API Key.

Keep the key on your backend only. Do not expose it in browser code, mobile apps, or public repositories.

2. Create a task

curl -X POST "https://aigptimage.com/api/v1/jobs/createTask" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: xxxxxxxxxxxx" \
  -d '{
    "model": "gpt-image-2-text-to-image",
    "input": {
      "prompt": "A cinematic portrait of a robot painter"
    }
  }'

Successful response:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxx"
  }
}

X-Request-ID is not required. If you do not send it, createTask can still succeed normally.

You should still send it in production. This value must be generated by your own backend, usually as:

a value such as xxxxxxxxxxxx
your own business request ID
your internal job ID

Why it matters:

if your backend retries the same logical request
if the client retries after a timeout
if a worker retries a failed delivery

then sending the same X-Request-ID lets the API return the existing task instead of creating a duplicate task and duplicate charge.

Best practice:

same logical request: reuse the same X-Request-ID
new logical request: generate a new X-Request-ID

3. Query the task

curl "https://aigptimage.com/api/v1/jobs/recordInfo?taskId=task_xxx" \
  -H "Authorization: Bearer sk-your-api-key"

When the task is still running:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxx",
    "model": "gpt-image-2-text-to-image",
    "state": "waiting",
    "param": "{\"model\":\"gpt-image-2-text-to-image\",\"input\":{\"prompt\":\"A cinematic portrait of a robot painter\"}}",
    "resultJson": null,
    "failCode": null,
    "failMsg": null,
    "costTime": null,
    "completeTime": null,
    "createTime": 1777459967759
  }
}

When the task succeeds:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_xxx",
    "model": "gpt-image-2-text-to-image",
    "state": "success",
    "param": "{\"model\":\"gpt-image-2-text-to-image\",\"input\":{\"prompt\":\"A cinematic portrait of a robot painter\"}}",
    "resultJson": "{\"resultUrls\":[\"https://cdn.example.com/result.png\"]}",
    "failCode": null,
    "failMsg": null,
    "costTime": 32241,
    "completeTime": 1777460000000,
    "createTime": 1777459967759
  }
}

When the task fails:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5f6ff8ea-ae97-4bb8-af5e-752ef4e96c0d",
    "model": "gpt-image-2-text-to-image",
    "state": "fail",
    "param": "{\"model\":\"gpt-image-2-text-to-image\",\"input\":{\"prompt\":\"360 equirectangular panorama, first-person view standing on stage at a massive concert with Michael Jackson performing, huge crowd cheering with hands raised, bright stage lights, smoke, dramatic spotlight, ultra realistic, cinematic concert atmosphere, immersive perspective, high detail, 2:1 aspect ratio, 4096x2048, no distortion\"}}",
    "resultJson": null,
    "failCode": "400",
    "failMsg": "Sorry, but the image we created may violate OpenAI's content policies.",
    "costTime": null,
    "completeTime": null,
    "createTime": 1777475010433
  }
}

Task states

State	Meaning
`waiting`	The task is queued or processing
`success`	The task completed successfully
`fail`	The task failed or was canceled

Even when a task fails, the recordInfo request itself can still return 200. Always use data.state as the final source of truth.

Credits

API calls use the same credit balance and model pricing rules as web generation. If a task fails after credits are consumed, the existing refund logic is used.