图片 API 对接文档从灵感，到可交付的图像。

export BASE_URL="https://api.example.com"
export UPLOAD_BASE_URL="https://uploads.example.com"
export API_KEY="YOUR_API_KEY"

curl "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "actions": [
        "generate",
        "edit"
      ]
    }
  ]
}

curl --max-time 420 "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: illustration-order-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗边看雨，柔和自然光，水彩插画",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto",
    "response_format": "url",
    "output_format": "png"
  }'

{
  "created": 1790000000,
  "status": "completed",
  "stage": "completed",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "data": [
    {
      "url": "https://api.example.com/v1/images/assets/22222222-2222-4222-8222-222222222222"
    }
  ]
}

{
  "size": "3:4",
  "resolution": "2K"
}

[
  {
    "size": "3:4",
    "resolution": "1k"
  },
  {
    "size": "3:4",
    "resolution": "2k"
  },
  {
    "size": "3:4",
    "resolution": "4k"
  }
]

# JSON 中填写
"size": "1536x2048"

# multipart 中填写
-F "size=3:4" -F "resolution=2k"

curl "$UPLOAD_BASE_URL/v1/images/uploads" \
  -F "file=@reference.png"

curl "$UPLOAD_BASE_URL/v1/images/uploads" \
  -H "Content-Type: image/jpeg" \
  --data-binary @reference.jpg

{
  "id": "33333333-3333-4333-8333-333333333333",
  "state": "ready",
  "url": "https://uploads.example.com/v1/images/uploads/44444444-4444-4444-8444-444444444444",
  "byte_size": 245760,
  "content_type": "image/png",
  "width": 1024,
  "height": 1024,
  "sha256": "示例：64位十六进制内容摘要"
}

curl --max-time 420 "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: edit-order-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "将图1的人物放在图2的场景中，保留人物面部特征和服装",
    "images": [
      {"image_url": "https://uploads.example.com/v1/images/uploads/IMAGE_ID_1"},
      {"image_url": "https://uploads.example.com/v1/images/uploads/IMAGE_ID_2"}
    ],
    "n": 1,
    "size": "1086x1448",
    "output_format": "jpg",
    "response_format": "url"
  }'

curl --max-time 420 "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留人物，将背景替换为雪山" \
  -F "image[]=@person.png" \
  -F "image[]=@landscape.jpg" \
  -F "size=1024x1024" \
  -F "output_format=png"

curl --max-time 420 "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cdn-generation-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "白色背景的陶瓷花瓶产品摄影",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url",
    "output_format": "jpeg",
    "cdn_key": "cdn_live_YOUR_CDN_KEY"
  }'

curl --max-time 420 "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留产品主体，将背景替换为浅灰色" \
  -F "image=@reference.png" \
  -F "size=1024x1024" \
  -F "response_format=url" \
  -F "output_format=jpeg" \
  -F "cdn_key=cdn_live_YOUR_CDN_KEY"

{
  "model": "gpt-image-2",
  "prompt": "一只坐在花园里的橘猫",
  "size": "1024x1024",
  "output_format": "jpeg",
  "cdn_key": "cdn_live_YOUR_CDN_KEY",
  "callback_url": "https://your-app.example.com/webhooks/images",
  "client_reference": "cdn-order-001"
}

{
  "status": "completed",
  "data": [
    {
      "url": "https://cdn.example.com/generated/11111111-1111-4111-8111-111111111111/0"
    }
  ]
}

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: async-order-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "极简白色陶瓷花瓶产品摄影",
    "n": 1,
    "size": "1024x1024",
    "output_format": "webp",
    "callback_url": "https://your-app.example.com/webhooks/images",
    "client_reference": "order-001"
  }'

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "stage": "queued",
  "offline_task": true,
  "status_url": "https://api.example.com/v1/images/tasks/11111111-1111-4111-8111-111111111111",
  "task_url": "/v1/tasks/11111111-1111-4111-8111-111111111111",
  "client_reference": "order-001"
}

curl "$BASE_URL/v1/images/tasks/$REQUEST_ID"

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "parent_request_id": null,
  "created": 1790000000,
  "status": "completed",
  "stage": "completed",
  "gateway_status": "completed",
  "offline_task": true,
  "status_url": "https://api.example.com/v1/images/tasks/11111111-1111-4111-8111-111111111111",
  "client_reference": "order-001",
  "data": [
    {
      "url": "https://api.example.com/v1/images/assets/22222222-2222-4222-8222-222222222222"
    }
  ],
  "final_status": "success"
}

{
  "event_id": "55555555-5555-4555-8555-555555555555",
  "event": "image.completed",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "status": "completed",
  "offline_task": true,
  "data": [
    {
      "url": "https://api.example.com/v1/images/assets/22222222-2222-4222-8222-222222222222"
    }
  ],
  "usage": null,
  "error": null,
  "completed_at": 1790000060
}

HMAC_SHA256(secret, timestamp + "." + raw_request_body)

import hashlib
import hmac
import time

def verify_callback(raw_body: bytes, timestamp: str, signature: str,
                    secret: str) -> bool:
    try:
        if abs(int(time.time()) - int(timestamp)) > 300:
            return False
    except (TypeError, ValueError):
        return False
    expected = "v1=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")

import base64
from pathlib import Path
# 当请求 output_format="png" 时
Path("result.png").write_bytes(base64.b64decode(result["data"][0]["b64_json"]))

curl -N --max-time 420 "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"海边日出","stream":true,"output_format":"png"}'

: working

data: {"b64_json":"iVBORw0...","type":"image_generation.completed","created_at":1790000060}

data: [DONE]

{
  "model": "gpt-image-2",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "将人物背景替换为海边，保留服装和面部特征"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://uploads.example.com/source.png"
          }
        }
      ]
    }
  ],
  "size": "1024x1024",
  "output_format": "png",
  "stream": false
}

{
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "![image](https://api.example.com/v1/images/assets/IMAGE_ID)"},
    "finish_reason": "stop"
  }]
}

curl -X POST "$BASE_URL/v1/images/tasks/$REQUEST_ID/resubmit" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"new-generation-order-002"}'

{
  "error": {
    "message": "图片格式无效或尺寸超过限制，请检查上传文件",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_image"
  }
}

import os, time, uuid
from pathlib import Path
import requests

base = os.environ["BASE_URL"].rstrip("/")
upload_base = os.environ["UPLOAD_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["API_KEY"]}

with open("reference.png", "rb") as f:
    r = requests.post(upload_base + "/v1/images/uploads",
                      files={"file": ("reference.png", f, "image/png")},
                      timeout=(10, 120))
r.raise_for_status()
image_url = r.json()["url"]

# 将 request_key 保存到业务数据库；同一次提交重试须复用此键和请求体。
request_key = str(uuid.uuid4())
payload = {
    "model": "gpt-image-2", "prompt": "保留主体，将背景替换为森林",
    "images": [{"image_url": image_url}], "n": 1,
    "size": "1024x1024", "output_format": "png",
    "callback_url": os.environ["CALLBACK_URL"],
    "client_reference": "order-001"
}
r = requests.post(base + "/v1/images/edits", json=payload,
                  headers={**headers, "Idempotency-Key": request_key},
                  timeout=(10, 120))
r.raise_for_status()
if r.status_code != 202:
    raise RuntimeError("Expected async acceptance: " + r.text)
accepted = r.json()
status_url = accepted["status_url"]  # 保存它，不要换到另一入口查询
print("request_id:", accepted["request_id"])

deadline = time.monotonic() + 900
while time.monotonic() < deadline:
    time.sleep(3)
    try:
        r = requests.get(status_url, timeout=(10, 30))  # 不需要 API Key
    except (requests.Timeout, requests.ConnectionError):
        continue
    if r.status_code in (429, 466, 477, 488, 502, 503, 504):
        time.sleep(5)
        continue
    r.raise_for_status()
    task = r.json()
    if task["status"] == "completed":
        for i, item in enumerate(task["data"]):
            image = requests.get(item["url"], timeout=(10, 120))
            image.raise_for_status()
            Path(f"result-{i}.png").write_bytes(image.content)
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error") or task["status"])
else:
    raise TimeoutError("本地等待结束，任务未必失败；继续使用已保存的 status_url 查询")

import { readFile, writeFile } from "node:fs/promises";

const base = process.env.BASE_URL.replace(/\/$/, "");
const uploadBase = process.env.UPLOAD_BASE_URL.replace(/\/$/, "");
const form = new FormData();
form.append("file", new Blob([await readFile("reference.png")],
  { type: "image/png" }), "reference.png");

async function jsonResponse(response) {
  const text = await response.text();
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
  return JSON.parse(text);
}
const uploaded = await jsonResponse(await fetch(uploadBase + "/v1/images/uploads", {
  method: "POST", body: form, signal: AbortSignal.timeout(120000)
}));
const requestKey = crypto.randomUUID(); // 持久化；网络重试时复用
const response = await fetch(base + "/v1/images/edits", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": requestKey
  },
  body: JSON.stringify({
    model: "gpt-image-2", prompt: "保留主体，背景改为蓝天",
    images: [{ image_url: uploaded.url }], n: 1,
    size: "1024x1024", output_format: "png", response_format: "url"
  }),
  signal: AbortSignal.timeout(420000)
});
console.log("request_id:", response.headers.get("x-request-id"));
const result = await jsonResponse(response);
for (const [index, image] of result.data.entries()) {
  const download = await fetch(image.url, { signal: AbortSignal.timeout(120000) });
  if (!download.ok) throw new Error(`Download HTTP ${download.status}`);
  await writeFile(`result-${index}.png`, Buffer.from(await download.arrayBuffer()));
}

页面完整可见时间 ≈ 排队 + 生成 +（可选 CDN 交付）+ 图片下载 + 解码 / 渲染

示例：生成 40 秒，图片文件 15 MB，实际下载速度只有 100 KB/s
仅下载就约需 150 秒，再加生成约 190 秒，页面可能 3 分钟以上才显示完整图片。

curl -L --max-time 180 -o /dev/null -sS \
  -w 'HTTP=%{http_code} DNS=%{time_namelookup}s CONNECT=%{time_connect}s TTFB=%{time_starttransfer}s TOTAL=%{time_total}s BYTES=%{size_download} SPEED=%{speed_download}B/s\n' \
  "$IMAGE_URL"