> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yir.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Submit and query a GPT Image 2 text-to-image task through either certified source-compatible route.

Before continuing, [create a Yir API key](/getting-started/authentication) and export it as `YIR_API_KEY`.

Generate one idempotency key for this logical request:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
export YIR_IDEMPOTENCY_KEY="$(uuidgen)"
```

Submit the task:

```bash theme={null}
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:

```bash theme={null}
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.