GPT Image 2 Async Image API

ReachAPI provides a task-based image API for GPT Image 2. Use this endpoint when you want task status polling, callback delivery, and final image URLs in data[].url.

The async API uses the public model code gpt-image-2-async. This code is only for POST /v1/images/create. The OpenAI-compatible Image API continues to use gpt-image-2 on /v1/images/generations and /v1/images/edits.

1. Overview

• Submit a task: POST https://direct.reachapi.ai/v1/images/create
• Query a task: GET https://direct.reachapi.ai/v1/tasks/{task_id}
• Model code: gpt-image-2-async
• Execution mode: async task
• Result field: data[].url

Request headers:

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

2. Submit a Task

Request body:

{
  "model": "gpt-image-2-async",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A children's book drawing of a veterinarian using a stethoscope to listen to a small animal.",
    "resolution": "1k",
    "aspect_ratio": "2:3",
    "quality": "medium",
    "background": "auto",
    "moderation": "auto",
    "output_format": "png"
  }
}

2.1 Top-Level Parameters

2.2 input Parameters

Notes:

• input.size takes priority over resolution + aspect_ratio
• For input.size, maximum edge length must be less than or equal to 3840px, both edges must be multiples of 16px, long-edge to short-edge ratio must not exceed 3:1, and total pixels must be at least 655,360 and no more than 8,294,400
• background=transparent cannot be used with output_format=jpeg
• If you need local image input, upload it first and pass a reachable HTTPS URL in input.image_urls

2.3 Standard Size Mapping

If a combination is not listed, use input.size to request the exact output size.

3. Billing

The async task API is billed per request by normalized resolution + quality.

quality is case-insensitive and is normalized to low, medium, or high. If omitted, it defaults to medium.

Billing resolution is determined as follows:

• If input.size is provided, its pixel dimensions are mapped to 1k, 2k, or 4k
• Otherwise, input.resolution is used; if omitted, it defaults to 1k

4. Examples

4.1 Text to Image

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "An editorial fashion photo of a silver handbag on a reflective pedestal, soft studio lighting",
      "resolution": "4k",
      "aspect_ratio": "2:3",
      "quality": "high",
      "output_format": "png"
    }
  }'

4.2 Custom Size

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "A fashion poster with a tall custom composition",
      "size": "2336x3504",
      "quality": "high",
      "output_format": "png"
    }
  }'

4.3 Image Editing

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "input": {
      "prompt": "Turn this sneaker photo into a premium e-commerce hero shot with a clean studio background",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "jpeg"
    }
  }'

5. Submit Response

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

6. Query a Task

Request:

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY"

Task statuses:

Success response:

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/gpt-image-2.png",
      "size": "1024x1536",
      "revised_prompt": "A children's book illustration of a veterinarian using a stethoscope."
    }
  ],
  "cost": {
    "spend": 0.12
  }
}

Failure response:

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

7. Callback

If callback_url is provided when the task is submitted, ReachAPI sends a POST request when the task reaches success or failed. The callback body uses the same JSON structure as the task query response.

Callback constraints:

• HTTPS only
• Maximum length: 2048
• localhost, .local, private-network, and local IP targets are rejected
• Single delivery timeout: 10s
• Failed delivery is retried up to 2 times, for a maximum of 3 delivery attempts

8. Constraints

• prompt is required and cannot be empty
• image_urls must contain server-accessible HTTPS URLs
• image_urls supports up to 14 images
• image_base64s is not supported
• n > 1 is not supported
• mask is not supported on this async endpoint
• output_compression is not supported
• user is not supported
• size must use pixel dimensions where the maximum edge is 3840px or less, both edges are multiples of 16px, the long-edge to short-edge ratio is no more than 3:1, and total pixels are between 655,360 and 8,294,400
• resolution supports 1k, 2k, and 4k
• aspect_ratio supports 1:1, 3:2, and 2:3 in standard mapping mode
• If size is not provided, resolution + aspect_ratio must match the standard mapping table
• quality supports low, medium, and high
• background, moderation, and output_format must use the documented enum values
• background=transparent does not support output_format=jpeg