System Docs

Request Example

curl https://your-domain.example/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://your-domain.example/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. Official Images-style request. b64_json is the default.
curl https://your-domain.example/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"
  }'

# 2. Return a URL and disable GPT2IMAGE prompt optimization.
curl https://your-domain.example/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,
    "prompt_optimization": false
  }'

# 3. Codex/Responses backend-only parameters. Plain Images API backends may ignore them.
curl https://your-domain.example/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. Force Web account scheduling for mixed groups within the configured pixel range. Non-mixed groups ignore force_web.
curl https://your-domain.example/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",
    "force_web": true
  }'

# 5. Streaming response. Accept: text/event-stream also enables streaming.
curl -N https://your-domain.example/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
  }'

Response Example

{
  "created": 1713833628,
  "data": [
    {
      "url": "https://your-domain.example/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://your-domain.example/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://your-domain.example/api/storage/generations/...","data":[{"url":"https://your-domain.example/api/storage/generations/...","revised_prompt":"..."}]}

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.
• 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://your-domain.example/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 'image[]=@/path/to/reference.png'

# 2. multipart multiple references + mask + Codex/Responses fields.
curl https://your-domain.example/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://your-domain.example/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,
    "prompt_optimization": false,
    "gptModel": "gpt-5.4-mini",
    "thinking": "low"
  }'

# 4. Force Web account scheduling for mixed groups within the configured pixel range. Non-mixed groups ignore force_web.
curl https://your-domain.example/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",
    "force_web": true
  }'

# 5. Streaming image edit.
curl -N https://your-domain.example/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'

Response Example

{
  "created": 1713833628,
  "data": [
    {
      "url": "https://your-domain.example/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://your-domain.example/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://your-domain.example/api/storage/generations/...","data":[{"url":"https://your-domain.example/api/storage/generations/...","revised_prompt":"..."}]}

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.

Request Example

# 1. JSON Agent image run. Ultra is required by default; admins can change externalApi.agent.
curl https://your-domain.example/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://your-domain.example/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://your-domain.example/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://your-domain.example/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://your-domain.example/api/storage/generations/...",
      "revised_prompt": "...",
      "output_role": "agent_draft"
    },
    {
      "url": "https://your-domain.example/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://your-domain.example/api/storage/generations/..."}

event: agent.completed
data: {"type":"agent.completed","generation_id":"...","generationId":"...","agent_round_count":2,"credits_consumed":8.42,"data":[{"url":"https://your-domain.example/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://your-domain.example/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://your-domain.example/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://your-domain.example/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://your-domain.example/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. /v1/chat/completions is still unsupported.
• 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.