Public API

GPT Image Hub API 文档

使用 Bearer API key 调用图片生成、模型列表、积分余额和生成记录查询接口。

创建 API key 查看生成示例

Base URLhttps://your-domain.com认证请求头Authorization: Bearer gih_live_...

快速开始

创建 API key

登录后进入账号页的 API Keys，创建并保存只显示一次的密钥。

检查模型和积分

调用 /api/v1/models 确认可用模型，再调用 /api/v1/credits 查看余额。

提交生成请求

调用 /api/v1/images/generations，并在响应中读取图片 URL 和积分消耗。

端点

GET/api/v1/modelsNo

List available image models, supported ratios, qualities, and credit cost.

GET/api/v1/creditsBearer

Read the credit balance for the user that owns the API key.

POST/api/v1/images/generationsBearer

Synchronously generate images from a prompt, with optional reference images.

GET/api/v1/generations/:generationIdBearer

Fetch a generation log and the images saved for that generation.

认证

除模型列表外，所有 v1 接口都需要在 Authorization 头中携带 API key。密钥明文只在创建时显示一次，服务端只保存 hash。

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

模型列表

模型接口返回模型 ID、供应商、支持的比例、质量、参考图限制和每张图消耗的积分。

curl https://your-domain.com/api/v1/models

GPT IMAGE 2

gpt-image-2

openai

API model IDgpt-image-2

Provideropenai

Provider modelgpt-image-2

积分消耗1 / image

默认参数auto, 1K

支持质量1K, 2K, 4K

支持比例auto, 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 5:4, 4:5, 21:9, 9:21, 2:1, 1:2, 3:1, 1:3

参考图最多张数: 16

请求字段

字段	值	说明
`model`	`gpt-image-2`	必须固定为该模型 ID
`aspect_ratio`	`auto`	可改为该模型支持的任意比例
`quality`	`1K`	可选质量: 1K, 2K, 4K
`n`	`1`	生成数量，范围 1 到 4
`reference_image`	`@./reference.png`	仅 multipart/form-data 使用，数量不能超过模型限制

JSON 调用

curl https://your-domain.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 with premium studio lighting",
    "aspect_ratio": "auto",
    "quality": "1K",
    "n": 1
  }'

参考图调用

curl https://your-domain.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 "aspect_ratio=auto" \
  -F "quality=1K" \
  -F "n=1" \
  -F "reference_image=@./reference.png"

积分余额

积分接口返回当前 API key 所属用户的余额、账户类型和即将过期的积分批次。

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

生成图片

图片生成接口是同步接口。生成前会扣积分；如果供应商失败，系统会自动退款。纯文本生成使用 JSON，带参考图使用 multipart/form-data。

JSON 请求

curl https://your-domain.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",
    "aspect_ratio": "1:1",
    "quality": "1K",
    "n": 1
  }'

带参考图请求

curl https://your-domain.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 "aspect_ratio=1:1" \
  -F "quality=1K" \
  -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": 1
  },
  "balance": {
    "credits": 119,
    "account_type": "PRO",
    "next_expiration": null
  }
}

查询生成记录

使用生成接口返回的 id 查询生成记录。只能查询当前 API key 所属用户的记录。

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

错误格式

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

HTTP	code	说明
400	`invalid_request`	The request body or parameters are invalid.
401	`missingApiKey`	The Authorization header is missing.
401	`invalidApiKey`	The API key does not exist or has been revoked.
401	`expiredApiKey`	The API key is expired.
402	`insufficientCredits`	The account does not have enough credits.
404	`notFound`	The requested resource was not found.
500	`generationFailed`	Image generation failed.

限制

当前生成接口为同步接口，最长执行时间 600 秒。
n 的范围是 1 到 4。
参考图支持 PNG、JPG、JPEG、WebP，单张最大 50MB。
参考图最大数量由模型的 reference_image_limit 决定。
当前版本暂未提供 webhook、异步任务队列和独立 rate limit。