Submit an asynchronous image task

curl --request POST \
  --url https://api.yingtu.ai/v1/images/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2-vip",
  "action": "generate",
  "prompt": "A silver watch on dark stone, no text"
}
'

{
  "task_id": "task_example",
  "status": "queued",
  "created_at": 1788307200
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "Insufficient balance for this request",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "Request body exceeds the current limit",
    "type": "new_api_error",
    "param": "",
    "code": "read_request_body_failed"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

POST

images

tasks

curl --request POST \
  --url https://api.yingtu.ai/v1/images/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2-vip",
  "action": "generate",
  "prompt": "A silver watch on dark stone, no text"
}
'

{
  "task_id": "task_example",
  "status": "queued",
  "created_at": 1788307200
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "Insufficient balance for this request",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "Request body exceeds the current limit",
    "type": "new_api_error",
    "param": "",
    "code": "read_request_body_failed"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "invalid_request_error",
    "param": "<string>",
    "code": "insufficient_user_quota"
  }
}

Use this endpoint for asynchronous image integrations. Set action=generate without input_images, or use action=edit with 1–16 Base64 source images. Add Idempotency-Key before any submit that may be retried. Nano Banana uses its model-specific K-size and aspect_ratio values. GPT Image uses explicit pixel dimensions and forwards quality; the selected upstream determines its effect. Both reverse-image routes use n=1. HTTP 202 means the task was accepted. Persist task_id, then poll Get task every 2–5 seconds until completed, failed, or expired. Completed results remain available for 24 hours and preserve the selected model family’s native response shape.

Try it creates a real billable task. The form can display an entered key in generated cURL, so use a development key and do not share the command or a credential-bearing screenshot.

Understand task fields

Choose action, model-specific controls, source-image input, and terminal handling.

Implement safe polling

Enforce a deadline, bounded retry, and model-specific result parsing.

Authorizations

Authorization

string

header

required

YingTu API key.

Headers

Idempotency-Key

string

Recommended unique retry key, up to 255 bytes. Reusing the same key with the same normalized request returns the original task; changing the request returns HTTP 409.

Maximum string length: 255

Body

application/json

Generate image task
Edit image task

Choose generation or editing with 1 to 16 source images. Model-specific size, aspect_ratio, and quality rules still apply.

model

enum<string>

required

Available options:

gemini-2.5-flash-image,

gemini-3.1-flash-lite-image,

gemini-3.1-flash-image,

gemini-3-pro-image,

gpt-image-2-web,

gpt-image-2-vip

action

string

required

Allowed value: "generate"

prompt

string

required

Minimum string length: 1

Example:

"A quiet reading room at sunrise, editorial photography"

size

enum<string>

Use model-specific values: Nano Banana uses its supported K tier or omits size where required; GPT Image uses an explicit pixel preset.

Available options:

1K,

2K,

4K,

1024x1024,

2048x2048,

3840x2160

aspect_ratio

enum<string>

Nano Banana only. GPT Image must omit aspect_ratio and use an explicit pixel size.

Available options:

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

quality

enum<string>

Forwarded for both GPT Image routes. The selected upstream determines how the requested value affects the result.

Available options:

low,

medium,

high,

auto

Example:

"low"

enum<integer>

default:1

Omit n or use 1.

Available options:

1

Response

Task accepted

task_id

string

required

Example:

"task_01JY8K6M6B4YQ3R8H4T6V2Z1AB"

status

string

required

Allowed value: "queued"

created_at

integer<int64>

required

Unix timestamp in seconds.

Example:

1788307200

Last modified on September 3, 2026