API / 接入指南
用熟悉的方式接入图像生成
统一的图像生成与编辑接口,支持文生图、参考图改图和异步任务。模型与价格见价格页面。
快速开始
向统一接口发送 JSON 请求。将示例中的服务地址和 API Key 替换为你的实际值。
Base URL
https://your-host请求方式
POST /v1/images/generations文生图
curl -X POST https://your-host/v1/images/generations \
-H "Authorization: Bearer sk-relay-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6",
"prompt": "一只坐在窗边的橘猫,柔和的午后光线",
"size": "1:1"
}'
参考图改图
在同一请求中传入公网图片地址即可进行图像编辑,最多支持 16 张参考图。
{
"model": "gpt-image-2.6",
"prompt": "保留主体,把背景换成雪山日落",
"images": ["https://your-cdn.com/reference.png"],
"size": "2:3"
}
参考图需要是公网可访问的 HTTP 或 HTTPS 图片地址,不支持 base64、data URI 或本地文件路径。
鉴权
在请求头中使用用户中心提供的 API Key。请将 Key 保存在服务端环境变量中,不要放进网页前端或公开仓库。
Authorization: Bearer sk-relay-your-key
注册后可在用户中心查看或重置 API Key。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 模型名称:gpt-image-2.6、gpt-image-2.5 或 gpt-image-2.0。 |
prompt | string | 生成或编辑图片的文字描述。 |
size | string | 画布比例或像素尺寸,例如 1:1、16:9、1024x1024。 |
resolution | string | 输出分辨率:1K、2K 或 4K。 |
quality | string | 画质档位;可用值按所选模型而异。 |
output_format | string | 输出格式,例如 png、jpeg 或 webp;2.6 还支持 gif、svg。 |
images | string[] | 可选参考图片 URL;传入后执行图像编辑。 |
async | boolean | 设为 true 后立即返回任务 ID,之后轮询任务状态。 |
支持的尺寸和参数限制会随模型而异;不支持的参数会返回明确的错误信息。
异步任务
大尺寸或耗时较长的请求可使用异步模式。提交成功后保存返回的任务 ID:
POST /v1/images/generations
{
"model": "gpt-image-2.6",
"prompt": "海边灯塔与星空",
"resolution": "4K",
"async": true
}
使用以下接口查询任务。任务完成后,结果图片地址会出现在响应中。
GET /v1/images/tasks/{id}
Authorization: Bearer sk-relay-your-key
任务状态包括 queued、running、succeeded 和 failed。可间隔数秒轮询,直到任务结束。
响应格式
同步请求成功后返回标准 JSON 与图片 URL。异步请求先返回任务 ID,查询接口在完成后提供结果。
{
"created": 1710000000,
"data": [{ "url": "https://your-cdn.com/result.png" }],
"relay": {
"request_id": "req_example",
"model": "gpt-image-2.6",
"resolution": "1K"
}
}
relay.price_credits 是本次请求的积分调用价。只有成功生成结果才会扣费,具体金额以当前价格表为准。
错误处理
| HTTP 状态 | 含义 | 处理建议 |
|---|---|---|
| 400 | 参数格式或取值不正确 | 根据响应中的错误说明修正请求。 |
| 401 | API Key 无效或缺失 | 检查鉴权请求头,并确认 Key 状态。 |
| 402 | 账户积分不足 | 联系站点客服充值后重试。 |
| 429 | 并发请求数超限 | 等待正在处理的请求完成后重试。 |
| 5xx | 服务或生成请求失败 | 稍后重试;失败请求不扣除生成积分。 |
每次调用的状态、耗时和扣费明细都可在用户中心的调用日志查看。