System Docs

Request Example

curl https://gpt2image.superapi.buzz/v1/models \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "created": 0,
      "owned_by": "gpt2image"
    }
  ]
}

Request Fields

Response And Streaming

Implementation Notes

• Only model listing is implemented; /v1/models/{model} is not implemented.
• Returned models are filtered by plan. Ultra users can see additional Responses models.

Request Example

curl https://gpt2image.superapi.buzz/v1/credits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY"

Response Example

{
  "object": "credit_balance",
  "account": {
    "balance": 15702.45,
    "total_earned": 20000,
    "total_spent": 4297.55,
    "status": "active"
  },
  "api_key": {
    "credit_limit": 1000,
    "credits_used": 12.7,
    "credits_remaining": 987.3,
    "unlimited": false
  }
}

Request Fields

Response And Streaming

Implementation Notes

• The API key quota only limits this key. Calls through the GPT2IMAGE-billed platform path still require enough account credits.
• When a user custom upstream API wins, GPT2IMAGE does not charge account credits or key quota.
• Failed-generation refunds, moderation settlement, and actual-size corrections also update key usage.

Request Example

# 1. Chat-to-image. URL is the default to keep response bodies small.
curl https://gpt2image.superapi.buzz/v1/chat/completions \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "image_model": "gpt-image-2",
    "messages": [
      { "role": "system", "content": "You are a professional poster designer." },
      { "role": "user", "content": "Create a 16:9 blue and white technology company poster" }
    ],
    "size": "1536x864",
    "quality": "high",
    "response_format": "url"
  }'

# 2. Multimodal input. image_url becomes a real reference image input for this turn.
curl https://gpt2image.superapi.buzz/v1/chat/completions \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "image_model": "gpt-image-2",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Use this product photo to create an ecommerce hero image" },
          { "type": "image_url", "image_url": { "url": "https://example.com/product.png" } }
        ]
      }
    ],
    "size": "1024x1024",
    "response_format": "url"
  }'

# 3. Streaming. Text uses chat.completion.chunk; partial images use a GPT2IMAGE extension event.
curl -N https://gpt2image.superapi.buzz/v1/chat/completions \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      { "role": "user", "content": "Create a futuristic city concept image" }
    ],
    "size": "1024x1024",
    "stream": true
  }'

Response Example

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "created": 1713833628,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Image generated.\n\n![generated image 1](https://gpt2image.superapi.buzz/api/storage/generations/...)",
        "images": [
          {
            "url": "https://gpt2image.superapi.buzz/api/storage/generations/...",
            "revised_prompt": "...",
            "generation_id": "gen_..."
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "images": [
    {
      "url": "https://gpt2image.superapi.buzz/api/storage/generations/...",
      "generation_id": "gen_..."
    }
  ],
  "generation_id": "gen_...",
  "generationId": "gen_...",
  "credits_consumed": 2.31,
  "usage": null
}

# stream=true SSE sample
data: {"id":"chatcmpl_...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Generating..."},"finish_reason":null}]}

event: chat.completion.partial_image
data: {"type":"chat.completion.partial_image","index":0,"partial_image_index":0,"url":"https://gpt2image.superapi.buzz/api/storage/generations/..."}

data: {"id":"chatcmpl_...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"generation_id":"gen_...","credits_consumed":2.31}

Request Fields

Response And Streaming

Implementation Notes

• Upstream API configs have two independent switches: Images upstream controls whether /v1/images/generations and /v1/images/edits call upstream /images/* or are converted to /responses + the image_generation tool; Chat Completions upstream only controls whether /v1/chat/completions calls upstream /chat/completions or /responses.
• Selecting chat_completions makes GPT2IMAGE /v1/chat/completions call the selected upstream's /chat/completions. This is better for pure chat compatibility, but image output depends on the upstream implementation. Agent and /v1/responses are not affected.
• OpenAI official Chat Completions does not define a standard generated-image response field. GPT2IMAGE extends the Chat Completions shape with choices[].message.images, top-level images, and Markdown image links in content. For strict official image-generation semantics, use /v1/images/generations, /v1/images/edits, or /v1/responses.
• This endpoint uses page Chat non-Agent mode. It does not inject web_search or continue_generation and does not return Agent task cards.
• The request kind is chat, so routing can select Web accounts, Codex/Responses accounts, or external API backends that support /responses. User custom upstream APIs still keep highest priority when available.
• Billing matches page Chat: a base Chat round charge first, then actual completed image output credits, moderation credits, and group multipliers.

Request Example

# 1. Official Images-style request. b64_json is the default.
curl https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute baby sea otter",
    "n": 1,
    "size": "1024x1024",
    "quality": "medium",
    "moderation": "auto",
    "background": "auto"
  }'

# 2. Return a URL and disable GPT2IMAGE prompt optimization.
curl https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "A cyberpunk city at night after rain, neon reflections",
    "n": 2,
    "size": "1024x1024",
    "quality": "high",
    "moderation": "low",
    "response_format": "url",
    "output_format": "webp",
    "output_compression": 85,
    "background": "transparent",
    "prompt_optimization": false
  }'

# 3. Codex/Responses backend-only parameters. Plain Images API backends may ignore them.
curl https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Create a 16:9 product campaign poster",
    "size": "1536x864",
    "response_format": "url",
    "output_format": "jpeg",
    "output_compression": 90,
    "gptModel": "gpt-5.4",
    "thinking": "high",
    "promptOptimization": false
  }'

# 4. Prefer Web account scheduling for mixed groups within the configured pixel range. Failed or exhausted Web routing falls back to Codex/Responses.
curl https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A 1:1 avatar poster",
    "size": "1024x1024",
    "response_format": "url",
    "web_first": true
  }'

# 5. Streaming response. Accept: text/event-stream also enables streaming.
curl -N https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A transparent glass futuristic coffee cup",
    "size": "1024x1024",
    "response_format": "url",
    "stream": true
  }'

# 6. Async mode. You may also append ?async=true. callback_url is optional.
curl https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "A transparent-background product icon",
    "size": "1024x1024",
    "response_format": "url",
    "output_format": "png",
    "background": "transparent",
    "async": true,
    "callback_url": "https://your-server.example/callback"
  }'

# 7. GPT2IMAGE extensions: transparent background + ISNet matte fallback, with safety prompt-repair retry disabled.
curl https://gpt2image.superapi.buzz/v1/images/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A transparent-background product icon",
    "size": "1024x1024",
    "response_format": "url",
    "output_format": "png",
    "background": "transparent",
    "transparent_matte": true,
    "prompt_repair": false
  }'

Response Example

{
  "created": 1713833628,
  "data": [
    {
      "url": "https://gpt2image.superapi.buzz/api/storage/generations/...",
      "revised_prompt": "..."
    }
  ],
  "generation_id": "gen_...",
  "generationId": "gen_...",
  "credits_consumed": 1.31,
  "usage": null
}

# SSE when stream=true
event: image_generation.partial_image
data: {"type":"image_generation.partial_image","index":0,"partial_image_index":0,"url":"https://gpt2image.superapi.buzz/api/storage/generations/..."}

event: image_generation.completed
data: {"type":"image_generation.completed","index":0,"generation_id":"...","generationId":"...","model":"gpt-image-2","size":"1024x1024","credits_consumed":1.31,"url":"https://gpt2image.superapi.buzz/api/storage/generations/...","data":[{"url":"https://gpt2image.superapi.buzz/api/storage/generations/...","revised_prompt":"..."}]}

# Immediate async=true response
{
  "id": "task_...",
  "object": "image.generation",
  "model": "gpt-image-2",
  "status": "processing",
  "created": 1713833628,
  "created_at": "2026-05-28T00:00:00.000Z",
  "generation_id": "gen_..."
}

# Poll task
curl https://gpt2image.superapi.buzz/v1/images/task_... \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY"

# Completed task response or callback payload
{
  "id": "task_...",
  "object": "image",
  "model": "gpt-image-2",
  "status": "completed",
  "created": 1713833628,
  "created_at": "2026-05-28T00:00:00.000Z",
  "completed": 1713833700,
  "completed_at": "2026-05-28T00:01:12.000Z",
  "data": [{"url": "https://gpt2image.superapi.buzz/api/storage/generations/..."}],
  "generation_id": "gen_...",
  "generationId": "gen_...",
  "credits_consumed": 1.31,
  "usage": null
}

Request Fields

Response And Streaming

Implementation Notes

• This endpoint does not call page /api/images/generate; it directly enters the shared service layer.
• When routed to a Responses account, the image request is converted into a Responses image_generation tool request.
• n/count is one HTTP request. A 10-image request creates 10 generation records and bills 10 outputs. GPT2IMAGE runs batch items with bounded parallelism based on the plan image-generation concurrency; items beyond that concurrency wait inside the same batch.
• Concurrency and queueing: the runtime uses one in-process image queue. Tasks are sorted by plan queue priority, then FIFO within the same priority, and are started only when both the global concurrency and per-user image-generation concurrency allow it. Global concurrency is configurable in Admin System Settings > Models > Global image generation concurrency; IMAGE_GENERATION_GLOBAL_CONCURRENCY is only the fallback default. Batch requests add a request-local bounded runner, so only the allowed number of batch items are started and the rest wait inside that batch instead of flooding the shared queue.
• Waiting in a queue does not create a generation record or charge image credits. If the shared queue wait exceeds IMAGE_GENERATION_QUEUE_TIMEOUT_MS, the API returns a 429-style error. The 20-minute runtime timeout starts only after an individual image task begins execution, and timeout settlement follows the failed-generation credit rules.
• Web backends cannot strictly control output dimensions or output format. GPT2IMAGE labels stored files by the detected image header and MIME.
• background=transparent is not universally supported. OpenAI's official docs currently list gpt-image-1.5, gpt-image-1, and gpt-image-1-mini as supporting transparent backgrounds, and png or webp output is usually required. Unsupported upstream models may reject the request with HTTP 400 instead of silently falling back.
• async tasks are process-local and expire after 30 minutes. A restart or multi-instance switch can make unfinished tasks unavailable for polling; already-sent callbacks are unaffected.
• If the actual generated dimensions differ from the requested size, GPT2IMAGE records and bills using the detected actual size.
• The official Images API may return usage. GPT2IMAGE usually returns usage: null, but GPT2IMAGE-billed credits are returned through top-level credits_consumed, error payloads, or streaming completion events. When a user custom upstream API wins, GPT2IMAGE does not charge credits.

Request Example

# 1. multipart upload reference image.
curl https://gpt2image.superapi.buzz/v1/images/edits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Turn the reference image into a cinematic poster" \
  -F n="1" \
  -F size="1024x1024" \
  -F quality="high" \
  -F moderation="auto" \
  -F response_format="url" \
  -F output_format="jpeg" \
  -F output_compression="90" \
  -F background="opaque" \
  -F 'image[]=@/path/to/reference.png'

# 2. multipart multiple references + mask + Codex/Responses fields.
curl https://gpt2image.superapi.buzz/v1/images/edits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Only redraw the masked area and keep the face unchanged" \
  -F size="1536x1024" \
  -F quality="medium" \
  -F response_format="b64_json" \
  -F promptOptimization="false" \
  -F gpt_model="gpt-5.4" \
  -F thinking="medium" \
  -F 'image[]=@/path/to/person.png' \
  -F 'image_2=@/path/to/style.png' \
  -F mask="@/path/to/mask.png"

# 3. JSON image URLs. Prefer images; image_url/image_urls are shortcuts.
curl https://gpt2image.superapi.buzz/v1/images/edits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Turn the reference into a clean ecommerce hero image",
    "images": [
      "https://example.com/reference.png",
      { "image_url": "https://example.com/detail.webp" }
    ],
    "image_url": "https://example.com/single-reference.png",
    "image_urls": ["https://example.com/extra.jpg"],
    "mask_url": "https://example.com/mask.png",
    "mask_image_url": "https://example.com/mask-alt.png",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto",
    "moderation": "low",
    "response_format": "url",
    "output_format": "webp",
    "output_compression": 80,
    "background": "transparent",
    "prompt_optimization": false,
    "gptModel": "gpt-5.4-mini",
    "thinking": "low"
  }'

# 4. Prefer Web account scheduling for mixed groups within the configured pixel range. Failed or exhausted Web routing falls back to Codex/Responses.
curl https://gpt2image.superapi.buzz/v1/images/edits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the person and make it look like a cinematic still",
    "images": ["https://example.com/reference.png"],
    "size": "1024x1024",
    "response_format": "url",
    "web_first": true
  }'

# 5. Streaming image edit.
curl -N https://gpt2image.superapi.buzz/v1/images/edits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Accept: text/event-stream" \
  -F model="gpt-image-2" \
  -F prompt="Keep the composition and convert it to watercolor illustration" \
  -F size="1024x1024" \
  -F response_format="url" \
  -F stream="true" \
  -F 'image=@/path/to/reference.png'

# 6. Async image edit. You may also append ?async=true. callback_url is optional.
curl https://gpt2image.superapi.buzz/v1/images/edits \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -F model="gpt-image-1.5" \
  -F prompt="Remove the background and output a transparent PNG" \
  -F size="1024x1024" \
  -F response_format="url" \
  -F output_format="png" \
  -F background="transparent" \
  -F async="true" \
  -F callback_url="https://your-server.example/callback" \
  -F 'image=@/path/to/reference.png'

Response Example

{
  "created": 1713833628,
  "data": [
    {
      "url": "https://gpt2image.superapi.buzz/api/storage/generations/...",
      "revised_prompt": "..."
    }
  ],
  "generation_id": "gen_...",
  "generationId": "gen_...",
  "credits_consumed": 1.31,
  "usage": null
}

# SSE when stream=true
event: image_edit.partial_image
data: {"type":"image_edit.partial_image","index":0,"partial_image_index":0,"url":"https://gpt2image.superapi.buzz/api/storage/generations/..."}

event: image_edit.completed
data: {"type":"image_edit.completed","index":0,"generation_id":"...","generationId":"...","model":"gpt-image-2","size":"1024x1024","credits_consumed":1.31,"url":"https://gpt2image.superapi.buzz/api/storage/generations/...","data":[{"url":"https://gpt2image.superapi.buzz/api/storage/generations/...","revised_prompt":"..."}]}

# async=true task polling and callback shape match /v1/images/generations.

Request Fields

Response And Streaming

Implementation Notes

• URL images are downloaded server-side and checked for public reachability, type, and size.
• Private networks, localhost, metadata/internal hosts, and URLs with credentials are rejected.
• Official JSON file_id image references are not implemented. Use public image_url or multipart uploads.
• background=transparent is not universally supported. OpenAI's official docs currently list gpt-image-1.5, gpt-image-1, and gpt-image-1-mini as supporting transparent backgrounds, and png or webp output is usually required. Unsupported upstream models may reject the request with HTTP 400 instead of silently falling back.
• async tasks are process-local and expire after 30 minutes. A restart or multi-instance switch can make unfinished tasks unavailable for polling; already-sent callbacks are unaffected.

Request Example

curl https://gpt2image.superapi.buzz/v1/images/task_... \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY"

Response Example

{
  "id": "task_...",
  "object": "image",
  "model": "gpt-image-2",
  "status": "completed",
  "created": 1713833628,
  "created_at": "2026-05-28T00:00:00.000Z",
  "completed": 1713833700,
  "completed_at": "2026-05-28T00:01:12.000Z",
  "data": [{"url": "https://gpt2image.superapi.buzz/api/storage/generations/..."}],
  "generation_id": "gen_...",
  "generationId": "gen_...",
  "credits_consumed": 1.31,
  "usage": null
}

# While still running (status:processing, no data yet)
{
  "id": "task_...",
  "object": "image.generation",
  "model": "gpt-image-2",
  "status": "processing",
  "created": 1713833628,
  "created_at": "2026-05-28T00:00:00.000Z",
  "generation_id": "gen_..."
}

Request Fields

Response And Streaming

Implementation Notes

• Tasks are in-memory objects that expire after 30 minutes; a restart or multi-instance switch makes unfinished tasks return 404, but a callback_url webhook that already fired is unaffected.
• You can only query tasks created by the user that owns the current API Key.
• The response matches exactly the task object POSTed to callback_url.

Request Example

# 1. Text-to-video. model is a full Firefly video id.
curl https://gpt2image.superapi.buzz/v1/videos/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-veo31-8s-16x9-1080p",
    "prompt": "A corgi running on the beach, cinematic camera, golden hour",
    "negative_prompt": "low resolution, blurry, watermark"
  }'

# 2. Image-to-video. image is an array of base64 data URLs (first frame / reference), up to 3.
curl https://gpt2image.superapi.buzz/v1/videos/generations \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-kling3-5s-9x16",
    "prompt": "Make the person slowly look up and smile",
    "image": ["data:image/png;base64,iVBORw0KGgo..."]
  }'

Response Example

{
  "created": 1713833628,
  "model": "firefly-veo31-8s-16x9-1080p",
  "data": [
    { "url": "https://gpt2image.superapi.buzz/api/storage/generations/..." }
  ],
  "credits_consumed": 240
}

Request Fields

Response And Streaming

Implementation Notes

• This endpoint is a GPT2IMAGE extension, not an official OpenAI endpoint. /api/v1/videos/generations is an alias.
• Video generation is long-running. GPT2IMAGE holds the connection with keep-alive until the video is ready or fails, so set a generous client read timeout.
• Billing = base credits per second (default 30) × duration in seconds × model-family multiplier, rounded up to two decimals. The duration comes from <dur> in the model id.
• Requires externalApi.images.generate by default (Starter or higher); admins can change it in the Plan Capability Matrix.

Request Example

# 1. JSON Agent image run. Ultra is required by default; admins can change externalApi.agent.
curl https://gpt2image.superapi.buzz/v1/agents/images \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "image_model": "gpt-image-2",
    "prompt": "Search public information about Zhejiang Shuangyuan Technology and iterate an enterprise poster",
    "size": "1536x1024",
    "quality": "high",
    "thinking": "medium",
    "agent_max_rounds": 3,
    "agent_force_max_rounds": false,
    "response_format": "url"
  }'

# 2. With reference image URLs. images / image_url / image_urls are merged and deduplicated.
curl https://gpt2image.superapi.buzz/v1/agents/images \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "image_model": "gpt-image-2",
    "prompt": "Analyze this product photo and create an ecommerce poster",
    "images": ["https://example.com/product.png"],
    "size": "1024x1024",
    "agent_max_rounds": 2
  }'

# 3. multipart reference image plus PDF/text attachments.
curl https://gpt2image.superapi.buzz/v1/agents/images \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -F model="gpt-5.4" \
  -F image_model="gpt-image-2" \
  -F prompt="Read the attachment and create a trade-show poster" \
  -F size="1536x1024" \
  -F response_format="url" \
  -F agent_max_rounds="3" \
  -F 'image[]=@/path/to/reference.png' \
  -F 'file=@/path/to/company-profile.pdf'

# 4. Streaming Agent events.
curl -N https://gpt2image.superapi.buzz/v1/agents/images \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "image_model": "gpt-image-2",
    "prompt": "Search first, then iterate a technology-blue enterprise poster",
    "size": "1536x1024",
    "stream": true,
    "agent_max_rounds": 2,
    "agent_force_max_rounds": true
  }'

Response Example

{
  "object": "agent.image_run",
  "created": 1713833628,
  "generation_id": "gen_...",
  "generationId": "gen_...",
  "model": "gpt-5.4",
  "size": "1536x1024",
  "response_text": "Research and poster generation completed.",
  "agent_round_count": 2,
  "credits_consumed": 8.42,
  "data": [
    {
      "url": "https://gpt2image.superapi.buzz/api/storage/generations/...",
      "revised_prompt": "...",
      "output_role": "agent_draft"
    },
    {
      "url": "https://gpt2image.superapi.buzz/api/storage/generations/...",
      "revised_prompt": "...",
      "output_role": "final"
    }
  ],
  "agent_events": [],
  "usage": null
}

# SSE when stream=true
event: agent.event
data: {"type":"agent.event","event":{"kind":"web_search","status":"completed","title":"Web search completed","detail":"Zhejiang Shuangyuan Technology official site"}}

event: agent.partial_image
data: {"type":"agent.partial_image","partial_image_index":0,"url":"https://gpt2image.superapi.buzz/api/storage/generations/..."}

event: agent.completed
data: {"type":"agent.completed","generation_id":"...","generationId":"...","agent_round_count":2,"credits_consumed":8.42,"data":[{"url":"https://gpt2image.superapi.buzz/api/storage/generations/...","output_role":"final"}]}

Request Fields

Response And Streaming

Implementation Notes

• This endpoint is a GPT2IMAGE extension, not an official OpenAI endpoint. /api/v1/agents/images is an alias.
• Ultra is required by default; admins can change externalApi.agent in the Plan Capability Matrix.
• It forces requiresResponsesBackend and never schedules Web accounts; it can use Codex/Responses accounts or external API backends that support /responses.
• It does not call page /api/images/chat; it shares the runImageGenerationForUser service layer with page Agent.
• generate_image_batch concurrent tooling is intentionally not exposed yet to preserve linear iteration and Responses native state.

Request Example

# 1. Minimal Responses image request. Requires Pro plan.
curl https://gpt2image.superapi.buzz/v1/responses \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Generate a 1:1 futuristic product render",
    "size": "1024x1024",
    "quality": "high",
    "moderation": "auto"
  }'

# 2. Explicit image_generation tool with image model.
curl https://gpt2image.superapi.buzz/v1/responses \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Generate a landscape technology product key visual",
    "tools": [{ "type": "image_generation", "model": "gpt-image-2" }],
    "size": "1536x864",
    "quality": "medium",
    "reasoning": { "effort": "low" },
    "store": true
  }'

# 3. Responses input with a reference image.
curl https://gpt2image.superapi.buzz/v1/responses \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Use this image as reference and make a winter poster" },
          { "type": "input_image", "image_url": "https://example.com/reference.png" }
        ]
      }
    ],
    "tools": [{ "type": "image_generation", "model": "gpt-image-2" }],
    "size": "1024x1024",
    "output_format": "webp",
    "output_compression": 85,
    "moderation": "low"
  }'

# 4. Continue a previous response and stream the result.
curl -N https://gpt2image.superapi.buzz/v1/responses \
  -H "Authorization: Bearer $GPT2IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "previous_response_id": "resp_previous_id",
    "input": "Add a moon based on the previous image",
    "tools": [{ "type": "image_generation", "model": "gpt-image-2" }],
    "size": "1024x1024",
    "reasoning": { "effort": "minimal" },
    "stream": true
  }'

Response Example

{
  "id": "resp_...",
  "object": "response",
  "created_at": 1713833628,
  "status": "completed",
  "model": "gpt-5.4",
  "output": [
    {
      "id": "ig_...",
      "type": "image_generation_call",
      "status": "completed",
      "result": "..."
    }
  ],
  "usage": null,
  "metadata": {
    "generation_id": "...",
    "credits_consumed": 1.31,
    "size": "1024x1024"
  }
}

# SSE when stream=true
event: response.output_item.done
data: {"type":"response.output_item.done","item":{"id":"ig_...","type":"image_generation_call","status":"completed","result":"..."}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","object":"response","created_at":1713833628,"status":"completed","model":"gpt-5.4","output":[{"id":"ig_...","type":"image_generation_call","status":"completed","result":"..."}],"usage":null,"metadata":{"generation_id":"...","credits_consumed":1.31,"size":"1024x1024"}}}

Request Fields

Response And Streaming

Implementation Notes

• This endpoint requires Pro plan or higher.
• This is not Chat Completions. Use /v1/chat/completions for normal chat-to-image, and this endpoint for Responses tool semantics.
• input_image supports image_url/data URLs. file_id/file inputs are not used as references today.
• If tools is provided without image_generation, GPT2IMAGE returns an error to avoid text-only responses.
• Page Chat mode uses normal multimodal chat/image semantics. Agent mode provides image_generation, web_search, and the linear continuation tool continue_generation by default without forcing tool_choice.
• Page Chat/Agent can read uploaded local text/code files as request context. Prompted server filesystem paths are not read.
• Page Chat/Agent base round credits are configured per plan in the admin Plan Capability Matrix. Defaults are 1 credit per Chat round and 3 credits per Agent round; completed images are additionally billed by detected output size and output count.
• Agent feeds the previous round's text, tool outputs, and generated draft images into the next round so the model can decide whether to refine again. The cap is IMAGE_AGENT_MAX_ROUNDS, default 3. Concurrent batch tools such as generate_image_batch are not wired into runtime yet because they need a native Responses state design first.
• Multiple Agent image_generation_call outputs are shown as automatic iteration variants, with the last image selected by default.