图片异步任务接口
本文档介绍图片生成任务、图片编辑任务和图片任务详情三个接口。它们统一接入现有 tasks 任务体系，提交成功后会返回本系统公开任务 ID，后续可通过任务详情接口查询处理状态和结果。
通用说明
- Base URL：
https://apinebula.ai - 鉴权方式：
Authorization: Bearer <API_KEY> - 请求路径前缀：
/v1 - 第三方异步参数：服务端调用上游时会自动追加
async=true，客户端调用本系统接口时不需要传。 - 计费模型：按请求里的
model，也就是“请求并计费模型”的系统配置计费。 - 失败退款：异步任务最终失败或取消时，会按任务预扣额度退回。
请求前先在令牌管理创建对应分组的令牌。提交后回到令牌列表，在目标令牌的密钥栏直接复制，并将完整 API Key 替换下方示例中的 YOUR_API_KEY。
状态说明
详情接口对外返回以 下状态：
| 状态 | 说明 |
|---|---|
completed | 任务成功 |
failed | 任务失败 |
queued | 任务排队中 |
in_progress | 任务处理中 |
上游状态兼容：
| 上游状态 | 本系统状态 |
|---|---|
succeeded / completed | completed |
failed / cancelled | failed |
queued / waiting | queued |
running / in_progress | in_progress |
1. 图片生成任务
接口
POST /v1/image-tasks/generations
Content-Type
application/json
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 图片模型，例如 gpt-image-2.5；请以当前模型广场中可用的图片模型为准 |
prompt | string | 是 | 图片生成提示词 |
quality | string | 否 | 图片质量，例如 high |
response_format | string | 否 | 响应格式，可选 url、b64_json，默认使用 url |
请求示例
curl --location 'https://apinebula.ai/v1/image-tasks/generations' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5",
"prompt": "一只猫坐在赛博朋克风格的窗边",
"quality": "high",
"response_format": "url"
}'
响应示例
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "image.task",
"model": "gpt-image-2.5",
"status": "queued",
"created_at": 1779104464
}
2. 图片编辑任务
接口
POST /v1/image-tasks/edits
Content-Type
application/json
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 图片模型，例如 gpt-image-2.5 |
prompt | string | 是 | 图片编辑提示词 |
images | array | 是 | 图片列表，使用图片 URL |
images[].image_url | string | 是 | 图片 URL |
quality | string | 否 | 图片质量，例如 high |
response_format | string | 否 | 响应格式，可选 url、b64_json，默认使用 url |
请求示例
curl --location 'https://apinebula.ai/v1/image-tasks/edits' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5",
"prompt": "把第一张图中的产品放到第二张图的办公桌场景中，保留真实阴影和透视关系",
"quality": "high",
"response_format": "url",
"images": [
{
"image_url": "https://example.com/product.png"
},
{
"image_url": "https://example.com/background.png"
}
]
}'
响应示例
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "image.task",
"model": "gpt-image-2.5",
"status": "queued",
"created_at": 1779104464
}
3. 获取图片任务详情
接口
GET /v1/image-tasks/{task_id}
Query 参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | boolean | 否 | 是否返回任务详情，传 true 时返回上游 detail 内容 |
请求示例
curl --location 'https://apinebula.ai/v1/image-tasks/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?detail=true' \
--header 'Authorization: Bearer YOUR_API_KEY'
普通响应示例
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "image",
"model": "gpt-image-2.5",
"status": "completed",
"created_at": 1779104464,
"completed_at": 1779104532
}
详细响应示例
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "image",
"model": "gpt-image-2.5",
"status": "completed",
"created_at": 1779104464,
"completed_at": 1779104532,
"detail": {
"data": [
{
"download_url": "https://cdnimage2.fapinebula.vip/<generated-file>.png"
}
],
"response_format": "url"
}
}
创建任务时传入的 response_format 会显示在 detail.response_format 中。建议使用默认值 url，成功后从 detail.data[].download_url 获取图片。选择 b64_json 时，任务详情响应正文也不会直接包含 Base64 图片，仍需读取 download_url。
失败响应示例
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"object": "image",
"model": "gpt-image-2.5",
"status": "failed",
"created_at": 1779104464,
"completed_at": 1779104532,
"error": {
"message": "task failed"
}
}
