# 异步图片任务

<a id="background-image"></a>

<a id="异步生图"></a>

## 异步生图

`POST /v1/responses`

本节不适用于 MidJourney（MJ）。这是公开的 Responses API 子集：仅用于后台图像任务，必须传 `background: true`，提交后通过任务 ID 轮询。

 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
 `thinking` | `boolean` | 否 | 是否开启思考，默认 false。仅 thinking\_supported=true 的 ChatGPT 原生图片模型支持；开启后每张加收模型配置的 thinking\_price 积分，不支持时返回 400。思考模式按模型公布的附加价格计费，不重复扣费。 放在请求顶层；后台任务保存该选项，幂等校验区分是否思考。 |
 `model` | `string` | 是 | 图片模型 ID。 |
 `background` | `boolean` | 是 | 必须为 true；当前公开的 Responses API 仅用于后台图像任务。 |
 `input` | `string \| array` | 是 | 提示词字符串，或包含 input\_text / input\_image 的消息数组。 |
 `input_image.image_url` | `string` | 否 | HTTP(S) URL 或 data:image/...;base64,...；不支持 file\_id。 |
 `size / quality` | `string` | 否 | 与同步图像接口使用相同的模型能力约束。 |
 `response_format` | `string` | 否 | url 或 b64\_json；完成结果格式与同步接口一致。 |
 `Idempotency-Key` | `header` | 否 | 用于避免后台任务重复提交；冲突时返回 422。 |

1 **提交** 返回 queued

2 **轮询** queued → in\_progress

3 **取结果** completed / failed / cancelled

 **异步生图**  `POST /v1/responses · 轮询 · 取消`

```bash
RESPONSE_ID=$(curl -s https://y.junlistudio.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: customer-order-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "background": true,
    "response_format": "url",
    "input": [{"role":"user","content":[
      {"type":"input_text","text":"保持主体，改成电影光影"},
      {"type":"input_image","image_url":"https://example.com/reference.png"}
    ]}]
  }' | jq -r .id)

# 轮询 queued / in_progress，直到 completed
curl https://y.junlistudio.com/v1/responses/$RESPONSE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# 尚未完成时可以取消
curl -X POST https://y.junlistudio.com/v1/responses/$RESPONSE_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<a id="responses-status"></a>

<a id="查询和取消异步任务"></a>

## 查询和取消异步任务

GET /v1/responses/{id} · POST /cancel

GET`/v1/responses/{id}`读取状态、错误和 output\[0\].result

POST`/v1/responses/{id}/cancel`取消尚未完成的任务

queuedin\_progresscompletedfailedcancelled

完成结果位于 `output[0].result`。如果使用 `response_format: "url"`，结果是临时 URL；使用 `b64_json` 时结果是内联内容。

参考图使用 `input_image.image_url`，支持 HTTP(S) URL 或 data URL，不提供 Files API 或 `file_id`。全局参考图上限为 15，模型还可能有更低限制。