Production integration

This guide reflects the current developer-preview contract: GPT Image 2 text-to-image through the certified KIE-compatible and APIMart-compatible routes. It does not promise unreleased models or arbitrary provider forwarding.

Authenticate safely

Keep the Yir API key on the server and send it only as a Bearer credential.

Track one logical request

Persist the idempotency key and task ID before polling.

Handle uncertain outcomes

Retry queries without turning a timeout into a second generation request.

Submission contract

Create an idempotency key

Generate one opaque value for one logical generation request. Reuse it only when retrying the identical request.

Submit through one compatible surface

Choose the KIE-compatible or APIMart-compatible shape your application already understands. Do not send an upstream provider credential.

Persist the returned task ID

Store the task ID with your local request record before starting background polling.

Poll to a terminal state

Use a bounded interval and an overall application deadline. Continue querying the same task after transient transport failures.

Never generate a fresh idempotency key merely because the submit response timed out. The original request may already have been accepted and may still create billing facts.

Required headers

string

required

A Yir credential in the form Bearer $YIR_API_KEY.

string

required

A caller-generated opaque identifier for the logical request. The same value with different request data is rejected.

Submit from your backend

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": "1:1",
    "resolution": "1k",
    "n": 1
  }'

const response = await fetch(
  "https://gateway.yir.ai/apimart/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YIR_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      model: "gpt-image-2",
      prompt: "A quiet observatory above a sea of clouds",
      size: "1:1",
      resolution: "1k",
      n: 1,
    }),
  },
);

if (!response.ok) throw new Error(`Yir rejected the request: ${response.status}`);
const task = await response.json();

import os
import uuid
import requests

response = requests.post(
    "https://gateway.yir.ai/apimart/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['YIR_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A quiet observatory above a sea of clouds",
        "size": "1:1",
        "resolution": "1k",
        "n": 1,
    },
    timeout=30,
)
response.raise_for_status()
task = response.json()

string

required

Stable APIMart-compatible task identifier to persist and query.

Choose a compatible surface

KIE-compatible
APIMart-compatible

Submit with POST /kie/api/v1/jobs/createTask, read data.taskId, and query GET /kie/api/v1/jobs/recordInfo?taskId=....

Submit with POST /apimart/v1/images/generations, read data[0].task_id, and query GET /apimart/v1/tasks/{id}.

Polling and recovery

Situation	Safe client behavior
Query returns an active status	Wait, then query the same task ID again.
Query request times out	Treat the outcome as unknown and retry the query.
Submit response times out	Retry the identical submit with the same idempotency key.
Terminal failure is returned	Stop polling and handle the stable public error.
Terminal success is returned	Persist the result URL before the retention window expires.

How fast should I poll?

Start conservatively, add jitter, and enforce an overall deadline in your application. A polling timeout is not proof that generation failed.

Should I submit a replacement when a task is slow?

No. Query the existing task ID. A second submit represents a second logical request unless it is an idempotent retry of identical data.

What may I include in support evidence?

Include the Yir task ID, source path, approximate UTC time, HTTP status, public error code, and a safe key prefix. Never include the complete key, prompt, source media, or raw provider response.

Your integration is ready for a controlled test when it persists both identifiers, reuses the idempotency key for submit retries, polls the same task ID, and never exposes the Yir API key to browser code.

Get started

Guides

Core concepts

Gateway reference

Help

Authenticate safely

Track one logical request

Handle uncertain outcomes

Submission contract

Required headers

Submit from your backend

Choose a compatible surface

Polling and recovery

Authenticate safely

Track one logical request

Handle uncertain outcomes

​Submission contract

​Required headers

​Submit from your backend

​Choose a compatible surface

​Polling and recovery

Submission contract

Required headers

Submit from your backend

Choose a compatible surface

Polling and recovery