接口说明
operation 是普通 JSON 字段，只能为 generation、edit 或 variation。任务先持久化再执行；网络结果不明确时不要换幂等键重提，应查询原任务。
认证：Bearer API Key
此接口可能产生真实费用。在线调试必须先从当前同源模型详情核对匹配渠道行的公开价格，再由你显式确认。
此接口可能产生真实费用。在线调试必须先从当前同源模型详情核对匹配渠道行的公开价格，再由你显式确认。
请求
请求头
| 名称 | 类型 | 说明 |
|---|---|---|
Idempotency-Key必填 | string | 所有写请求都必须携带。为避免重复付费，同一个业务意图必须复用同一个值。 |
JSON 请求体
| 字段 | 类型 | 说明 |
|---|---|---|
operation必填 | generation | edit | variation | 明确选择操作；平台不会猜测。 |
model必填 | string | 公开逻辑模型 ID。 |
prompt | string | 提示词；是否必填与长度上限由模型操作能力决定。 |
images | string[] | 有序 HTTPS URL 或带 MIME 的图片 Data URL 数组。 |
mask | string | 编辑时可用的一张遮罩，须符合模型闭集和尺寸约束。 |
n | integer | 请求结果数，默认 1；上限来自模型详情。 |
size | string | 像素值或比例，必须命中渠道行公布的精确值。 |
size_tier | 1k | 2k | 4k | 部分模型使用的分辨率档位，必须与 size 组成已公布组合。 |
quality | string | 质量档位；是否支持由最终渠道行决定。 |
response_mode | async | sync | 默认 async；sync 最多等待 60 秒，超时后仍返回同一任务。 |
response_format | url | b64_json | 结果表示方式，默认 url。 |
所有业务写请求都必须提供非空、业务唯一的 Idempotency-Key。相同 Key 和相同规范化请求会返回原任务，同一 Key 对应不同请求会返回 409。
Python 与 TypeScript
示例只包含占位凭据，不会自动重试。生产代码应从安全环境读取 OGA Key，并为每个业务操作生成唯一幂等键与请求 ID。
Python · httpx
import os
import httpx
response = httpx.post(
os.environ["OGA_BASE_URL"] + "/api/v1/images/tasks",
headers={
"Authorization": "Bearer <YOUR_OGA_API_KEY>",
"Content-Type": "application/json",
"Idempotency-Key": "<UNIQUE_IDEMPOTENCY_KEY>",
"X-Request-Id": "<UUID_V4>",
"Accept-Language": "zh-CN",
},
json={
"model": "gpt-image-2",
"operation": "generation",
"prompt": "A quiet blue observatory above the clouds",
"n": 1,
"size": "1024x1024",
"quality": "standard",
"response_format": "url",
"response_mode": "async"
},
timeout=30,
)
response.raise_for_status()
print(response.json())TypeScript · fetch
const response = await fetch(
`${process.env.OGA_BASE_URL}/api/v1/images/tasks`,
{
method: "POST",
redirect: "error",
headers: {
"Authorization": "Bearer <YOUR_OGA_API_KEY>",
"Content-Type": "application/json",
"Idempotency-Key": "<UNIQUE_IDEMPOTENCY_KEY>",
"X-Request-Id": "<UUID_V4>",
"Accept-Language": "zh-CN",
},
body: JSON.stringify(
{
"model": "gpt-image-2",
"operation": "generation",
"prompt": "A quiet blue observatory above the clouds",
"n": 1,
"size": "1024x1024",
"quality": "standard",
"response_format": "url",
"response_mode": "async"
}
),
},
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());响应
JSON 接口使用统一响应信封。HTTP 状态表达请求结果，业务错误不会伪装成 HTTP 200。
| HTTP | 含义 |
|---|---|
200 | 请求成功 |
202 | 任务已持久化并进入异步处理 |
400 | 业务参数或过滤条件无效 |
401 | 缺少或无效的 API Key |
402 | 余额不足，未受理付费任务 |
403 | API Key 已禁用或无权访问 |
409 | 幂等键冲突或当前状态冲突 |
422 | 请求结构校验失败 |
500 | 服务内部错误 |
完整成功响应示例（可选字段可能因状态不同而变化）
{
"code": 0,
"message": "success",
"data": {
"task_id": "task_01JEXAMPLE",
"status": "queued",
"terminal_reason": null,
"model": "gpt-image-2",
"operation": "generation",
"size": "1024x1024",
"size_tier": null,
"quality": "standard",
"response_format": "url",
"input_count": 0,
"has_mask": false,
"response_mode": "async",
"auto_async_on_timeout": null,
"requested_count": 1,
"result": null,
"result_expires_at": null,
"result_expired": false,
"poll_url": "/api/v1/tasks/task_01JEXAMPLE",
"retry_after_seconds": 5,
"channel": null,
"routing": {
"strategy": "stable_first",
"total_attempts": 0,
"switch_count": 0,
"attempts": []
},
"error": null,
"billing": {
"status": "held",
"currency": "USD",
"reserved_amount": "0.023000",
"charged_amount": "0.000000",
"refunded_amount": "0.000000",
"released_amount": "0.000000",
"balance_after_settlement": null
},
"created_at": "2026-08-10T00:00:00Z",
"updated_at": "2026-08-10T00:00:00Z",
"completed_at": null
},
"request_id": "8f25b42f-2ed1-4ad7-99de-61d7f779bc7b",
"timestamp": "2026-08-10T00:00:00Z"
}重要边界
- 这是常用接口导览中唯一的付费 POST；不存在 generations、edits 或 variations 别名。
- 一次请求可能产生真实费用。价格以提交时锁定的公开快照为准。
- 上游受理状态未知时不会换渠道或自动重提。
- 调试器不会仅凭 WIDTHxHEIGHT 语法放行自定义尺寸；必须同时命中某条当前可路由渠道公开的 custom_size_constraints。