# 请求约定

接入地址、JSON、请求标识、时间、金额和翻页的通用规则。

所有接口都遵守下面这些约定。具体字段见各接口页面。

## 接入地址

把接入地址保存为 `CHENVOYA_BASE_URL`，不带末尾斜杠；文档里的路径都接在它后面，例如 `POST /v1/video/generations`。地址显示在「[API 概览](./api-docs-zh-api.md#connection)」和控制台的「接入」页。

## JSON

请求体和响应体都是 JSON，发送请求体时带 `Content-Type: application/json`。字段名和取值都是英文标识，原样使用，不要翻译。

## 请求标识

可以在请求头 `X-Request-ID` 里放自己的请求标识；无效或重复的值由服务替换。响应头 `X-Request-ID` 返回本次请求最终使用的标识，最长 64 个字符。排查问题时把它和错误响应里的 `trace_id` 一起提供给我们。

## 标识

| 标识 | 格式 | 示例 |
| --- | --- | --- |
| 任务 ID | 字母开头，4–128 个字母、数字、`_` 或 `-` | `task_32ae2a5177b310d3bc1ec83a98f63889` |
| 素材 ID | `ast-` 加 32 位小写十六进制 | `ast-` 开头 |
| 请求关联标识 `request_id` | 与任务 ID 相同的格式 | `req_6acd96894df9798feb0ddb21e5a52d70` |
| 费用关联标识 `billing_correlation_id` | 与任务 ID 相同的格式 | `billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0` |

## 时间

时间字段是自 Unix 纪元起的整数秒，例如 `created_at`。还没有发生的时间（如未开始任务的 `started_at`）为 `null`。

## 金额

金额是美元，写成带六位小数的字符串，例如 `"0.361564"`。尚未确定的金额为 `null`。不要把金额转成浮点数再计算。

## 翻页

列表接口用游标翻页：`page_size` 控制每页条数（1–100，默认 50），响应里的 `next_cursor` 放进下一次请求的 `cursor`。最后一页的 `next_cursor` 为 `null`。游标不透明，不要自己构造；不是服务为本团队这个列表签发的游标返回 `400 invalid_request`。

## 错误

错误响应包含 `error` 对象和 `trace_id`。按 `error.code` 处理，详见「[处理错误](./api-docs-zh-errors.md)」。

## 下一步

- [认证](./api-docs-zh-authentication.md)：用 Bearer 方式在请求头发送 API 密钥。
- [幂等与重试](./api-docs-zh-idempotency.md)：用同一个 Idempotency-Key 重试，不会重复创建任务，也不会重复扣费。
- [API 概览](./api-docs-zh-api.md)：接入地址、认证、错误格式和全部接口。