快速开始
本页展示最小接入流程：创建生成任务，然后查询任务结果。
1. 创建 API Key
打开 API Keys 页面，然后点击 Create API Key。
API Key 只能保存在你的服务端。不要放在浏览器代码、移动端 App 或公开仓库中。
2. 创建任务
curl -X POST "https://aigptimage.com/api/v1/jobs/createTask" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-H "X-Request-ID: xxxxxxxxxxxx" \
-d '{
"model": "gpt-image-2-text-to-image",
"input": {
"prompt": "A cinematic portrait of a robot painter"
}
}'成功响应：
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_xxx"
}
}X-Request-ID 对 createTask 不是必填。不传这个 header，请求也可以正常成功。
但在生产环境里，仍然强烈建议你传这个值。它必须由你自己的服务端生成，常见方式包括：
- 例如
xxxxxxxxxxxx - 你自己的业务请求 ID
- 你内部的任务 ID
它的作用是：
- 当你的服务端重试同一个逻辑请求时
- 当客户端因为超时重试时
- 当 worker 重试失败任务时
如果继续使用同一个 X-Request-ID，API 可以直接返回已有任务，避免重复创建任务和重复扣费。
最佳实践：
- 同一个逻辑请求：复用同一个
X-Request-ID - 新的逻辑请求：生成新的
X-Request-ID
3. 查询任务
curl "https://aigptimage.com/api/v1/jobs/recordInfo?taskId=task_xxx" \
-H "Authorization: Bearer sk-your-api-key"任务仍在处理中：
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_xxx",
"model": "gpt-image-2-text-to-image",
"state": "waiting",
"param": "{\"model\":\"gpt-image-2-text-to-image\",\"input\":{\"prompt\":\"A cinematic portrait of a robot painter\"}}",
"resultJson": null,
"failCode": null,
"failMsg": null,
"costTime": null,
"completeTime": null,
"createTime": 1777459967759
}
}任务成功：
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_xxx",
"model": "gpt-image-2-text-to-image",
"state": "success",
"param": "{\"model\":\"gpt-image-2-text-to-image\",\"input\":{\"prompt\":\"A cinematic portrait of a robot painter\"}}",
"resultJson": "{\"resultUrls\":[\"https://cdn.example.com/result.png\"]}",
"failCode": null,
"failMsg": null,
"costTime": 32241,
"completeTime": 1777460000000,
"createTime": 1777459967759
}
}任务失败：
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5f6ff8ea-ae97-4bb8-af5e-752ef4e96c0d",
"model": "gpt-image-2-text-to-image",
"state": "fail",
"param": "{\"model\":\"gpt-image-2-text-to-image\",\"input\":{\"prompt\":\"360 equirectangular panorama, first-person view standing on stage at a massive concert with Michael Jackson performing, huge crowd cheering with hands raised, bright stage lights, smoke, dramatic spotlight, ultra realistic, cinematic concert atmosphere, immersive perspective, high detail, 2:1 aspect ratio, 4096x2048, no distortion\"}}",
"resultJson": null,
"failCode": "400",
"failMsg": "Sorry, but the image we created may violate OpenAI's content policies.",
"costTime": null,
"completeTime": null,
"createTime": 1777475010433
}
}任务状态
| State | 含义 |
|---|---|
waiting | 排队中或处理中 |
success | 任务成功 |
fail | 任务失败或取消 |
即使任务失败，recordInfo 这个 HTTP 请求本身也仍然可能返回 200。最终结果一定要以 data.state 为准。
积分
API 调用和网页端共用同一个积分余额和模型计费规则。任务失败后，会使用现有的积分返还逻辑。