GPT Image Hub API 文档

除模型列表外，所有 v1 接口都需要在 Authorization 请求头中携带 API 密钥。原始密钥只会在创建时显示一次；服务器只保存哈希值。

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

模型接口会返回模型 ID、服务商、支持的画幅比例、支持的画质、参考图限制和每张图的积分消耗。

curl https://www.gptimagehub.com/api/v1/models

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

积分接口会返回该 API 密钥所属用户的余额、账户类型和即将到期的积分信息。

curl https://www.gptimagehub.com/api/v1/credits \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

图像生成接口默认等待生成完成。设置 async 为 true 可以立即获得 generation id，并通过 /api/v1/generations/:generationId 轮询结果。生成前会扣除积分；如果服务商生成失败或返回的图片少于请求数量，会自动退还相应积分。

JSON 请求

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a transparent perfume bottle on black marble",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

异步任务

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero-image" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "async": true
  }'

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "queued",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "created_at": "2026-04-30T08:00:00.000Z",
  "images": [],
  "usage": {
    "credits": 0,
    "credits_requested": 7
  },
  "poll_url": "https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id"
}

参考图请求

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the reference image and render it as a premium studio product shot" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1" \
  -F "reference_image=@./reference.png"

响应

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "succeeded",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "images": [
    {
      "id": "clx_image_id",
      "object": "image",
      "url": "https://cdn.example.com/generations/user/image.png",
      "created_at": "2026-04-30T08:00:00.000Z"
    }
  ],
  "usage": {
    "credits": 7
  },
  "balance": {
    "credits": 113,
    "account_type": "PRO",
    "next_expiration": null
  }
}

使用生成接口返回的 ID 查询保存的生成日志和图片 URL。API 密钥只能读取同一用户名下的生成记录。

curl https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "error": {
    "message": "Invalid request body",
    "code": "invalidRequest"
  }
}

• 生产环境中，同步生成最多可运行 800 秒。
• n 必须在 1 到 4 之间。
• 参考图支持 PNG、JPG、JPEG 和 WebP。包含所有参考图在内的整个请求必须小于 4.5MB（图片总大小请保持在 4MB 以内）。超过此大小的请求会在到达 API 之前被托管平台直接以纯文本 413 拒绝，因此请先调整图片尺寸或进行压缩。
• 最大参考图数量由各模型的 reference_image_limit 决定。
• 速率限制：每个 API 密钥每分钟 60 次生成请求，每个 IP 地址每分钟 120 次。每个响应均携带 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset 响应头；429 还会携带 Retry-After。
• 如需安全地重试生成，请发送 Idempotency-Key 请求头（最多 120 个字符）。使用相同的 API 密钥重复提交相同的 key 将返回最初的生成结果，而不会再次扣费。
• 异步模式返回 202 及 poll_url。目前暂不支持 Webhook。