Quickstart

Before continuing, create a Yir API key and export it as YIR_API_KEY. Generate one idempotency key for this logical request:

export YIR_IDEMPOTENCY_KEY="$(uuidgen)"

Reuse that value when retrying the same logical request. Generate a new value for a new task. Reusing one key with different request data is rejected.

KIE-compatible flow

Submit one GPT Image 2 text-to-image task:

curl --request POST \
  --url "https://gateway.yir.ai/kie/api/v1/jobs/createTask" \
  --header "Authorization: Bearer $YIR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $YIR_IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2-text-to-image",
    "input": {
      "prompt": "A quiet observatory above a sea of clouds",
      "resolution": "1K",
      "aspect_ratio": "16:9"
    }
  }'

Read the task ID from data.taskId, then query it:

export YIR_TASK_ID="task-id-from-data.taskId"

curl --request GET \
  --url "https://gateway.yir.ai/kie/api/v1/jobs/recordInfo?taskId=$YIR_TASK_ID" \
  --header "Authorization: Bearer $YIR_API_KEY"

The KIE-compatible terminal states are success and fail. While the task is active, the state is waiting or generating.

APIMart-compatible flow

Generate a new idempotency key because this is a new logical task:

export YIR_IDEMPOTENCY_KEY="$(uuidgen)"

Submit the task:

curl --request POST \
  --url "https://gateway.yir.ai/apimart/v1/images/generations" \
  --header "Authorization: Bearer $YIR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $YIR_IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A quiet observatory above a sea of clouds",
    "size": "16:9",
    "resolution": "1k",
    "n": 1
  }'

Read the task ID from data[0].task_id, then query it:

export YIR_TASK_ID="task-id-from-data[0].task_id"

curl --request GET \
  --url "https://gateway.yir.ai/apimart/v1/tasks/$YIR_TASK_ID" \
  --header "Authorization: Bearer $YIR_API_KEY"

The APIMart-compatible terminal states are completed and failed. While the task is active, the status is pending or processing.

Production polling

Poll with a bounded interval and an overall deadline. Treat a transport timeout or an active status as unknown or still running—not as a confirmed generation failure. Keep querying the same task ID instead of submitting a replacement unless your application has made that retry decision explicitly.

Get started

Guides

Core concepts

Gateway reference

Help

KIE-compatible flow

APIMart-compatible flow

Production polling

​KIE-compatible flow

​APIMart-compatible flow

​Production polling

KIE-compatible flow

APIMart-compatible flow

Production polling