通用约定
适用于所有接口的约定。
请求与响应
| 项目 | 约定 |
|---|---|
| 协议 | 仅 HTTPS |
| 数据格式 | JSON，UTF-8。带请求体的请求需带 Content-Type: application/json |
| 基础地址 | https://api.nanoapi.ai/v1 |
时间
ISO 8601 格式的 UTC 时间，例如 2026-10-22T08:30:00Z。例外是两个使用 Unix 秒的 HTTP 头：响应头 X-RateLimit-Reset 和回调请求头 webhook-timestamp。
金额
单位为美元，用十进制字符串表示，最多 6 位小数，例如 "1.50"、"0.05"。billing 里只有 billed_seconds 是数字（而非字符串），最多 3 位小数。
不要用浮点数解析金额。请使用十进制类型，例如 Python 的 decimal.Decimal，或 JavaScript 的十进制运算库。
ID
ID 全小写，带表示对象类型的短前缀。
| 对象 | 前缀 | 示例 |
|---|---|---|
| 任务 | tk_ | tk_01jb8z5q4w3e2r1t0y9u8i7o6p |
| API Key | ak_ | ak_01jb7y2m3n4p5q6r7s8t9v0w1x |
| 回调事件 | ev_ | ev_01jb9a3k7m2n5p8q4r6s1t0v9w |
| 请求 | rq_ | rq_01jb... |
更早创建的对象保留原来的 ID（例如 task_01JB…），照样可以使用。请把 ID 当作不透明的字符串：不要解析前缀、不要转换大小写，拿到什么就原样传回。完整的 API Key 本身仍以 nf_ 开头。
请求追踪
每个响应都带 X-Request-Id 响应头，错误响应中的 error.request_id 与它相同。请记录到日志，反馈问题时提供它。
版本
版本号在路径中（/v1）。
- 新增字段不算不兼容改动，不升版本。请忽略不认识的字段，响应和回调内容都是如此。
- 不兼容的改动发布为新版本
/v2。
但请求里传了不认识的参数，会返回 400 invalid_request。
超时
创建任务要先读取源视频，通常需要 1–3 秒，最长约 35 秒：客户端超时请设为 60 秒以上。
分页
列表接口使用游标分页。
| 参数 | 说明 |
|---|---|
limit | 每页条数，默认 20，最大 100 |
starting_after | 上一页最后一条记录的 id，返回它之后的记录 |
{ "object": "list", "data": [], "has_more": true }has_more 为 false 时即为最后一页。查询类接口限制为每秒 1 次，翻页时请控制间隔（见限流与限额）。
curl "https://api.nanoapi.ai/v1/tasks?limit=100&starting_after=tk_01jb8z5q4w3e2r1t0y9u8i7o6p" \
-H "Authorization: Bearer $NANOAPI_API_KEY"