GPT Image API 文档

概览

GPT Image API 用一个账户和一个 API Key 统一提供图片生成与图片编辑能力。请求采用熟悉的 OpenAI 风格字段（model、prompt、size、quality），可降低迁移成本，模型供应商细节被稳定的 API 表面隐藏。GPT Image 2 面向文字密集场景设计——拼写、位置以及小而密的文字仍建议在发布前审核。

快速开始

1. 创建 API Key

登录控制台，在 Settings → API Keys 创建密钥，保存到服务端环境变量，切勿在浏览器端暴露：

GPT_IMAGE_API_KEY=sk_...

2. 选择模型

3. 发送第一个请求

curl https://api.gptimageapi.dev/v1/images/generations \
  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a ceramic coffee cup",
    "size": "1:1"
  }'

成功响应会在 data[].url 返回生成的图片地址。

认证

GPT Image API 使用 API Key 进行标准 Bearer 认证：

Authorization: Bearer $GPT_IMAGE_API_KEY

密钥安全要点：

• 不要把 API Key 写进浏览器端 JavaScript，请从你的后端调用 GPT Image API。
• 团队成员离职或密钥泄露时，在 Settings → API Keys 轮换密钥。
• 为开发、测试、生产环境分别使用独立的密钥。

无效或缺失凭据返回 401 Unauthorized：

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

端点

图片请求支持 OpenAI 兼容的同步端点；长时间运行的图片任务也可以异步提交，并通过 GET /v1/tasks/{id} 轮询，直到状态变为 completed 或 failed。

图片生成

POST /v1/images/generations

图片编辑

POST /v1/images/edits

获取任务结果

GET /v1/tasks/{id}

任务状态：submitted、processing、completed、failed。每个任务会报告 0–100 的 progress，完成后返回 credits_cost。

响应格式

图片响应遵循 OpenAI 图片结构：

{
  "created": 1766880000,
  "data": [
    {
      "url": "https://cdn.gptimageapi.dev/generated/image.png"
    }
  ]
}

异步任务提交后立即返回任务 id：

{
  "status": "submitted",
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "progress": 0,
  "created_at": 1703884800,
  "model": "gpt-image-2"
}

质量档与积分

模型支持相应参数时，积分由输出尺寸档和质量档共同决定：

quality=auto 按 high 计费，size=auto 默认使用 1K 档。模型可用性和积分规则可能调整，提交生产请求前请查看实时价格页，并在额度中核对账户记录。

错误处理

只对瞬时错误（429、500、503）做指数退避重试。遇到 402 insufficient_credits，请引导用户前往额度或账单，在业务流程内自助解决。

代码示例

Node.js

const response = await fetch('https://api.gptimageapi.dev/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    size: '1:1',
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
console.log(result.data?.[0]?.url ?? result);

Python

import os
import requests

response = requests.post(
    "https://api.gptimageapi.dev/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_IMAGE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1",
    },
)

response.raise_for_status()
result = response.json()
print(result["data"][0]["url"])

异步图片生成（Node.js）

提交任务后，轮询 GET /v1/tasks/{id} 直到任务完成：

// 1. 提交异步任务
const submit = await fetch('https://api.gptimageapi.dev/v1/async/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    size: '1:1',
  }),
});
const task = await submit.json();
console.log(task.id); // task_01KPQ7J7DWB7QZ3WCEK3YVPBRA

// 2. 轮询直到任务完成
let status = task.status;
while (status === 'submitted' || status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const poll = await fetch(`https://api.gptimageapi.dev/v1/tasks/${task.id}`, {
    headers: { Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}` },
  });
  const result = await poll.json();
  status = result.status;
  if (status === 'completed') {
    console.log(result.result?.data?.[0]?.url ?? result);
  } else if (status === 'failed') {
    throw new Error(result.error?.message ?? 'Task failed');
  }
}

异步图片生成（Python）

import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['GPT_IMAGE_API_KEY']}"}

# 1. 提交异步任务
submit = requests.post(
    "https://api.gptimageapi.dev/v1/async/images/generations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1",
    },
)
submit.raise_for_status()
task = submit.json()
print(task["id"])

# 2. 轮询直到任务完成
while task["status"] in ("submitted", "processing"):
    time.sleep(2)
    task = requests.get(f"https://api.gptimageapi.dev/v1/tasks/{task['id']}", headers=headers).json()

if task["status"] == "completed":
    print(task["result"]["data"][0]["url"])
else:
    raise RuntimeError(task.get("error", {}).get("message", "Task failed"))

下一步

• 在在线体验中先试写提示词，再写代码。
• 查看价格了解积分套餐与模型成本。
• 在控制台管理密钥、额度与用量记录。