> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apipod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 欢迎使用 APIPod

> 通过 APIPod 异步媒体 API 生成图片和视频。

APIPod 为账户中已启用的图片和视频模型提供统一的异步任务 API。应用只需要选择公开的 APIPod 模型 ID，供应商选择、鉴权、计费、任务执行和请求追踪由 APIPod 在同一个 API 地址后完成。

```text theme={null}
https://api.apipod.ai
```

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/zh-CN/quickstart">
    使用完整可运行的请求创建并轮询 GPT Image 2 任务。
  </Card>

  <Card title="身份认证" icon="key-round" href="/zh-CN/authentication">
    创建 API Key、检查账户访问权限并安全发送凭据。
  </Card>

  <Card title="图片模型" icon="image" href="/zh-CN/gpt-image-2/gpt-image-2">
    浏览图片生成与编辑模型，并查看每个模型的准确请求 Schema。
  </Card>

  <Card title="视频模型" icon="video" href="/zh-CN/veo/3-1-fast">
    浏览文本、图片和参考素材驱动的视频生成模型。
  </Card>
</CardGroup>

## 可以构建什么

| 工作负载 | APIPod 入口                     | 请求行为                   |
| ---- | ----------------------------- | ---------------------- |
| 图片生成 | `POST /v1/images/generations` | 接受请求并返回用于轮询的 `task_id` |
| 视频生成 | `POST /v1/videos/generations` | 接受请求并返回用于轮询的 `task_id` |
| 价格估算 | `POST /v1/pricing/estimate`   | 执行前估算请求成本              |

图片和视频请求都是异步流程：创建响应只确认任务已受理，之后通过状态响应交付生成结果。

## 媒体任务流程

先根据生成结果选择端点，再打开具体模型页面确认请求契约：

* **图片任务**使用 `/v1/images/generations` 和 `/v1/images/status/{task_id}`。
* **视频任务**使用 `/v1/videos/generations` 和 `/v1/videos/status/{task_id}`。
* **模型页面**定义可用的提示词、媒体输入、宽高比、时长、分辨率和其他模型专属字段。
* 不适合持续轮询时，可以通过 **Webhook** 接收任务终态事件。

## 与 APIPod 一致的请求生命周期

1. **认证。** 在服务端发送 `Authorization: Bearer <API_KEY>`。`GET /v1/account/status` 可作为轻量的凭据和账户探针。
2. **发现。** 在 API 参考的图片、视频分组中浏览模型，也可以通过顶部 Models 链接打开实时产品目录。
3. **选择契约。** 严格使用文档中的模型 ID，并按模型页面右侧 OpenAPI 面板校验。即使属于同一系列，不同模型支持的字段和限制也可能不同。
4. **执行。** 使用 `Idempotency-Key` 创建图片或视频任务，并持久化返回的 `task_id`。
5. **完成。** 轮询 `GET /v1/images/status/{task_id}` 或 `GET /v1/videos/status/{task_id}`，也可以配置 Webhook 接收终态事件。
6. **持久化与观测。** 将结果资源保存到自己的持久化存储，并记录 `task_id`、`X-Request-ID`、HTTP 状态码和机器可读错误码。

<Note>
  媒体创建接口返回成功，只表示 APIPod 已受理任务，并不表示生成已完成。`pending` 和 `processing` 都是非终态，只有 `completed`、`failed` 或 `cancelled` 才应停止轮询。
</Note>

## 生产环境检查清单

* API Key 只保存在后端，不要提交到代码仓库或打包进浏览器资源。
* 只在操作可安全重试时重试。媒体创建请求结果不明确时，复用相同的 `Idempotency-Key` 和完全不变的 JSON 请求体。
* 对轮询以及临时性的 `429`、`503` 或 `5xx` 使用带抖动的有上限指数退避。
* 在启动后台轮询前先持久化 `task_id`，并将结果 URL 复制到自己控制的存储中。
* 先根据状态判断成功或失败，再读取 `result` 或错误字段；未知机器码也应保留以兼容未来扩展。
* 不适合持续轮询时使用 [Webhook](/zh-CN/webhooks)，错误和重试语义参见[错误处理](/zh-CN/error-codes)。

<CardGroup cols={3}>
  <Card title="异步任务" icon="clock-3" href="/zh-CN/asynchronous-tasks">
    图片和视频生成的轮询、终态和结果交付。
  </Card>

  <Card title="API Reference" icon="file-code-2" href="/zh-CN/gpt-image-2/gpt-image-2">
    模型专属 schema，以及 cURL、Python、Go、Rust 和 JavaScript 示例。
  </Card>

  <Card title="价格估算" icon="calculator" href="https://www.apipod.ai/pricing">
    查看价格，并在消耗额度前估算请求成本。
  </Card>
</CardGroup>