> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 图片接口返回 201，为什么还没有图片？

> POST /v1/images/tasks 返回 HTTP 201 仅表示图片任务已受理并排队，需保存 data.id 并轮询 GET /v1/tasks/{task_id} 直至状态变为 succeeded 才能获取成图。

`POST /v1/images/tasks` 返回 HTTP `201` 只表示网关已受理图片任务并进入队列，不表示渲染已完成。客户端应将返回的 `data.id` 保存到订单或素材记录中，随后通过 `GET /v1/tasks/{task_id}` 轮询最终结果。

## 轮询任务生命周期

每次轮询之间按 `data.poll_after_seconds`（图片任务为 5 秒）等待，查询 `GET /v1/tasks/{task_id}` 不受速率限制。

```bash
curl -sS 'https://api.beatapi.io/v1/tasks/<task_id>' \
  -H "Authorization: Bearer $BEATAPI_API_KEY"
```

* **`queued` 或 `processing`**：界面继续展示处理中，等待 `data.poll_after_seconds` 后再次轮询。
* **`succeeded`**：从 `data.output.media[].url`（或 `data.output.r2_url`）读取图片链接，并尽快下载转存到自有存储。
* **`failed`**：任务失败时 `GET /v1/tasks/{task_id}` 仍返回 HTTP `200`，需读取 `data.error_code`、`data.error_message` 和 `data.retryable`，并回到素材记录核对输入参数。

## 任务失败后的余额处理

已受理任务最终进入 `failed` 时，网关会自动退还创建时预扣的额度：`usage.credits_charged` 与 `usage.credits_settled` 均为 `0`，`usage.credits_refunded` 记录退回金额。

## 合同与相关问题

在[图片 API](/zh/image-api)查模型入参，在[任务状态说明](/zh/quick-guide#get-task-status)查状态和结果字段。如果创建请求超时、还没拿到任务 ID，按[幂等重试说明](/zh/faq/model-idempotent-retry)处理。

[返回AI 模型问题索引](/zh/faq/models)。