本页目录
GPT Image 2 API
通过一套稳定的异步 API，用提示词和可选参考图生成一张 GPT Image 2 图片。imya 负责任务状态、实时套餐计费和生成资产。
REST API · v1 · 异步任务
完成第一次调用
API 采用异步任务：先创建任务并保存 task ID，再查询任务，直到结果生成完成。
- 1
创建 API Key
在 imya 账户设置中生成一枚密钥。
- 2
创建任务
提交模型 ID、提示词和输出参数。
- 3
获取结果
轮询任务，直到成功或失败。
身份验证与幂等
API Key 通过 Bearer Token 发送。每个生成 POST 还必须带唯一 Idempotency-Key，安全重试不会重复创建任务或扣费。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY创建图片生成任务
创建异步 GPT Image 2 任务，并原子扣除通过 credits_reserved 返回的准确积分。
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gpt-image-order-001" \
-d '{
"model": "gpt-image-2",
"prompt": "A luxury perfume product photo on warm marble, soft studio light",
"aspect_ratio": "1:1",
"resolution": "1K",
"n": 1
}'查询任务
返回最新任务状态、最终积分消耗、生成资产或结构化错误。建议轮询间隔至少 5 秒；更频繁的请求仍占用速率额度，但不会刷新上游状态。
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 使用 gpt-image-2。 |
| prompt | string | 是 | 图片生成提示词，长度为 1 至 20,000 个字符。 |
| aspect_ratio | string | 否 | auto、1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、3:1、1:3、21:9 或 9:21。 |
| resolution | string | 否 | 1K、2K 或 4K；部分比例只支持 1K。 |
| n | number | 否 | 必须为 1，每次只生成一张。 |
| image_urls | string[] | 否 | 1 到 16 张公开 HTTPS 参考图。 |
返回结构
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 13
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:42.000Z",
"credits_reserved": 13,
"credits_used": 13,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}积分计费
基础价为 1K 10 积分、2K 15 积分、4K 24 积分。服务端再应用 API Key 所属用户的当前套餐系数，并通过 credits_reserved 返回本次实时扣费。示例为普通账户生成 1K 图片时的 13 积分；客户端应始终使用返回值，n 固定为 1。
任务状态
pending任务已接收，正在等待处理。
processing模型正在生成请求的内容。
succeeded生成完成，data 中包含最终资产。
failed生成失败，请读取结构化 error 对象。
错误码
400缺少 Idempotency-Key 或 JSON 格式错误。
401API Key 缺失或无效。
402账户积分不足。
403API 账户已停用。
404任务不存在，或不属于当前账户。
409同一幂等键被用于不同请求体。
413请求体超过 64 KiB。
415Content-Type 必须是 application/json。
422模型、提示词、比例、分辨率、n 或参考图无效。
429API Key 达到速率或并发上限。
5xx本次请求无法完成或提交。
Imya 公共 API 统一规则
以下规则适用于所有公开图片和视频生成接口；模型独有参数和价格仍以本页参数表为准。
扣费与安全重试
新任务被接受时，服务端会原子扣除 credits_reserved 显示的准确积分。使用相同 Idempotency-Key 和相同请求体重试，只会返回原任务，不会再次扣费。
超时与退款
任务在 30 分钟内没有进入最终状态时会失败。符合条件的积分只退一次，而且保留原积分到期日。
速率与并发限制
每个 API Key 每 60 秒最多请求 120 次；同一账户最多同时运行 5 个图片任务或 3 个视频任务。429 返回可能包含 Retry-After；如有该字段请遵守。
轮询与任务归属
使用创建任务时返回的 id 查询 GET /v1/tasks/{id}，建议间隔至少 5 秒。更频繁的请求仍会占用 API Key 速率额度，但不会刷新上游状态。只有创建任务的账户可以读取；当前不提供 webhook、SDK 或批量提交。
错误与内容安全
公开错误会经过净化，不会暴露上游凭据、内部地址或基础设施信息。不安全提示词可能在生成前以 prompt_blocked 拒绝。
图片结果保留
免费账户的图片结果保存 7 天，有效付费或 Lifetime 账户最长保存 30 天。删除后响应的 status 为 failed、error.code 为 media_deleted，而不是没有数据的成功状态。
GPT Image 2 API 生产环境接入指南
稳定的 GPT Image 2 接入应当被当作一个小型异步任务系统，而不是一次长时间 HTTP 请求。将模型选项放在配置中，保存每个 Imya 任务返回的 id，并让重试结果可预期。以下做法覆盖从本地示例进入生产环境时最重要的环节。
以模型契约选择参数
提交前，请根据本页参数表校验每个请求。开发阶段先使用最小的受支持输入和输出设置，只在产品确实需要时才提高质量、尺寸、时长或参考图数量。对用户提供的提示词和文件，应先在自己的服务端检查长度、文件类型和大小。
参考图流程需保持图片顺序，并确认用户有权使用每张上传图片。
设计可恢复的异步流程
提交图片任务后，将返回的 id 和业务任务一起保存，再由后台工作器查询状态。建议 GET /v1/tasks/{id} 的轮询间隔至少 5 秒；更频繁的请求仍占用 API Key 速率额度，但不会刷新上游状态。公开状态只有 pending、processing、succeeded 和 failed。任务有 30 分钟硬截止时间，因此工作器应在收到终态或到达边界时停止。当前不提供 webhook、SDK 或批量提交，请使用 HTTP 请求和轮询接入。
- 01更新页面前，先持久化 id、status、credits_reserved 和请求标识。
- 02遇到短暂网络错误时退避重试，429 按 Retry-After 执行，不要因传输错误自动创建新的付费任务。
- 03同一账户最多同时运行 5 个图片任务；每个 API Key 每 60 秒最多 120 次请求。
让扣费与重试结果确定
新任务被接受时，credits_reserved 返回的准确积分会被原子扣除。每次有意创建新任务时生成一个 Idempotency-Key，并与请求一起保存。相同 Key 和相同请求体重放时，只会返回原任务，不会再次扣费。如果用户更改了请求，应创建新 Key。
当失败任务符合退款条件时，Imya 只退回一次积分，并保留原积分到期日。公开 status 仍是 failed：结算处理中时 error.code 为 refund_pending，退款完成后响应会出现 credits_refunded。按 id 对账，不要由客户端自行发放积分。
保护密钥、任务归属和生成结果
将 API Key 保留在服务端，绝不要写入浏览器或移动端安装包。将每个返回的 id 与创建它的登录用户或工作区关联，展示结果前验证归属。公开错误已经净化；排查时记录自己的请求 ID 和任务 id，不要暴露提示词、私密媒体地址或凭据。
免费账户的图片结果保存 7 天，有效付费或 Lifetime 账户最长保存 30 天。媒体被删除后，响应的 status 为 failed，error.code 为 media_deleted。如果产品需要更长期保留，应在得到用户同意并符合隐私政策的前提下，复制到自己控制的存储中。
生产上线清单
- 提交前校验模型专用字段。
- 每个预期任务保存一个幂等 Key 和请求体。
- 持久化任务状态，并以不短于 5 秒的间隔轮询。
- 实施账户并发与 API Key 速率限制。
- 明确处理四种公开 status；status 为 failed 时检查 error.code 中的 media_deleted 或 refund_pending，并用 credits_refunded 确认退款完成。
- 密钥仅留在服务端，并定义结果保留政策。
常见问题
工作器应多久轮询一次？
间隔不得短于 5 秒。任务仍在处理时，可以使用更慢的退避轮询。
什么时候扣积分？
新任务被接受时，credits_reserved 的准确积分会被原子扣除。
重试会重复扣费吗？
相同 Idempotency-Key 和完全相同的请求体重放时不会，系统会返回原任务。
任务最终失败后怎么做？
向用户显示清晰的产品错误，保留 id 用于支持，并让服务端完成符合条件的一次性退款。通过 credits_refunded 确认结果，不要等待一个不存在的 refunded 状态。
接入前想先测试模型？
打开 GPT Image 2 在线生成器，无需写代码即可比较提示词和输出设置。
在线试用 GPT Image 2