> ## 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 URL、请求头、响应结构、请求 ID 和幂等语义。

## 基础地址与版本

本文档中的所有端点均使用：

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

稳定公开 API 位于 `/v1` 下。JSON 请求体使用 UTF-8 编码，并发送 `Content-Type: application/json`。

平台还在 `/openai/v1` 下提供 OpenAI 原生的**同步**图片接口，供直接使用 OpenAI Images API 的工具接入——参见 [OpenAI 兼容图片接口](/zh-CN/openai-image-sync)。

### 长时间同步请求

默认域名 `https://api.apipod.ai` 在边缘网关配置了 **120 秒 read timeout**。非流式且可能超过该时长的请求——包括 OpenAI 兼容的同步图片接口（`/openai/v1/images/*`）——必须使用专用的长请求域名：

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

两个域名提供相同的路径与鉴权方式。只要请求可能运行超过两分钟，请选用 `https://apid.apipod.ai`；短请求、流式请求与异步任务请求使用 `https://api.apipod.ai`。

## 媒体端点

| 方法     | 路径                              | 用途                       |
| ------ | ------------------------------- | ------------------------ |
| `POST` | `/v1/images/generations`        | 创建异步图片任务                 |
| `GET`  | `/v1/images/status/{task_id}`   | 查询当前认证账号拥有的图片任务          |
| `POST` | `/v1/videos/generations`        | 创建异步视频任务                 |
| `GET`  | `/v1/videos/status/{task_id}`   | 查询当前认证账号拥有的视频任务          |
| `POST` | `/openai/v1/images/generations` | 同步生成图片并等待结果（OpenAI 原生格式） |
| `POST` | `/openai/v1/images/edits`       | 同步编辑图片并等待结果（OpenAI 原生格式） |

## 请求头与响应头

| 请求头/响应头               | 要求         | 说明                        |
| --------------------- | ---------- | ------------------------- |
| `Authorization`       | 模型和任务端点必填  | `Bearer <APIPOD_API_KEY>` |
| `Content-Type`        | JSON 请求体必填 | `application/json`        |
| `Idempotency-Key`     | 媒体创建端点建议发送 | 防止跨重试重复创建任务               |
| `X-Request-ID`        | 响应         | API 请求追踪标识                |
| `X-Request-Cost`      | 支持的计费端点响应  | 可用时返回格式化请求成本              |
| `X-Idempotent-Replay` | 重放响应       | 重放已保存的创建响应时为 `true`       |
| `Retry-After`         | 部分可重试错误    | 建议等待秒数                    |

## 响应结构

图片和视频端点通常返回 APIPod 标准结构：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

创建端点与状态查询端点的 `data` 对象并不相同。请以具体模型页或任务页的 OpenAPI 契约为准，不要假设所有媒体端点都会返回相同字段。

## 媒体创建幂等性

`Idempotency-Key` 是 `POST /v1/images/generations` 和 `POST /v1/videos/generations` 的可选请求头，但生产环境强烈建议使用。

* 最大长度为 255 个字符。
* 幂等范围包含当前 API Key、HTTP 方法和路由。
* 使用相同键和等价 JSON 请求体时会重放已保存响应。
* 相同键配合不同请求会返回 HTTP `409` 和 `idempotency_conflict`。
* 首次请求仍在处理时重试会返回 HTTP `409`、`idempotency_in_progress` 和 `Retry-After: 1`。
* 当前服务实现会保留已完成幂等记录 7 天。

<Warning>
  新 HTTP 请求只有携带原始 `Idempotency-Key` 才能受到幂等保护。发送首次请求前，应先把该键与业务操作持久化保存。
</Warning>

## ID 与时间戳

* `task_id` 标识公开异步媒体任务，是状态查询的必需参数。
* `X-Request-ID` 标识 HTTP 请求，应写入运行日志。
* 任务状态响应中的 `completed_at` 是 Unix 秒级时间戳。
* Webhook 中的 `created_at` 和 `completed_at` 是 JSON 时间戳。