任务
查询、列出任务，以及任务对象的全部字段。
每次生成都是一个任务。任务由模型接口创建（例如 POST /v1/genjutsu），用下面的接口查询。
查询任务
GET https://api.nanoapi.ai/v1/tasks/{task_id}curl https://api.nanoapi.ai/v1/tasks/tk_01jb8z5q4w3e2r1t0y9u8i7o6p \
-H "Authorization: Bearer $NANOAPI_API_KEY"返回任务对象。任务处于 queued 或 running 时，响应带 Retry-After: 15，即建议的轮询间隔。任务不存在或不属于你时返回 404 not_found。
列出任务
GET https://api.nanoapi.ai/v1/tasks| 查询参数 | 说明 |
|---|---|
ids | 最多 20 个任务 ID，英文逗号分隔，用来一次查询多个任务。传了它，其他筛选条件和分页都会被忽略 |
status | queued、running、succeeded 或 failed |
product | 目前只有 genjutsu |
api_key_id | 创建任务的 Key（api_key.id） |
created_after / created_before | 创建时间范围（ISO 8601） |
limit / starting_after | 见分页 |
curl "https://api.nanoapi.ai/v1/tasks?ids=tk_01jb8z5q4w3e2r1t0y9u8i7o6p,tk_01jb8z7c2d4f6g8h0j2k4m6n8p" \
-H "Authorization: Bearer $NANOAPI_API_KEY"返回 { "object": "list", "data": [...], "has_more": false }，每一项都是完整的任务对象，按创建时间倒序。请按 id 对应结果，不要依赖顺序。查询类接口限制为每秒 1 次，等待中的任务请合并成一次查询（见限流与限额）。
任务对象
模型接口和上面的接口都返回它，回调里的 data 也是它。
{
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"product": "genjutsu",
"model": "genjutsu-1.0",
"status": "succeeded",
"input": {
"mode": "motion_control",
"image_urls": ["https://example.com/person.png"],
"video_url": "https://example.com/dance.mp4",
"prompt": "",
"resolution": "720p"
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://file.example.com/…/0.mp4",
"preview_url": "https://file.example.com/…/0_compressed.mp4"
}
],
"billing": {
"currency": "USD",
"frozen": "4.095",
"charged": "4.095",
"refunded": "0.00",
"billed_seconds": 15
},
"error": null,
"metadata": { "order_id": "A1001" },
"webhook_url": "https://example.com/hooks/nanoapi",
"api_key": { "id": "ak_01jb7y2m3n4p5q6r7s8t9v0w1x", "name": "production", "prefix": "nf_8Kx2" },
"created_at": "2026-10-22T08:30:00Z",
"started_at": "2026-10-22T08:31:05Z",
"finished_at": "2026-10-22T08:47:12Z",
"elapsed_seconds": 1032
}| 字段 | 说明 |
|---|---|
id | 任务 ID，例如 tk_01jb8z5q4w3e2r1t0y9u8i7o6p，见 ID |
product | 产品，目前是 genjutsu |
model | 模型版本，例如 genjutsu-1.0 |
status | queued、running、succeeded 或 failed，见状态 |
input | 创建时传入的模型参数 |
num_outputs | 请求的结果个数 |
outputs | 生成结果，任务成功前为空，见结果 |
billing | 金额（美元），见计费字段 |
error | 失败原因，未失败时为 null，见失败原因 |
metadata | 创建时传入的自定义键值对 |
webhook_url | 创建时传入的回调地址，没有则为 null |
api_key | 创建任务的 Key：id、name 和 prefix（Key 开头几位）。Key 删除或重置后仍保留 |
created_at / started_at / finished_at | ISO 8601 时间；started_at 和 finished_at 发生前为 null |
elapsed_seconds | 耗时（秒）：从创建到结束，排队和生成都算在内；任务结束前为 null |
状态
queued ──开始生成──→ running ──┬─→ succeeded（扣费）
│ └─→ failed（冻结金额退回）
└──30 分钟内未开始──→ failed（queue_timeout）succeeded 和 failed 是终态，不会再改变。任务不能取消。
结果
| 字段 | 说明 |
|---|---|
index | 序号，从 0 开始 |
type | Genjutsu 为 video |
url | 结果文件，可直接下载 |
preview_url | 宽 600 像素、无声的压缩版，用于预览；没能生成时为 null |
拿到链接的人都能打开文件，不希望公开的结果请不要分享链接。结果文件目前不会删除，但需要长期保存的请复制到你自己的存储中。
计费字段
| 字段 | 说明 |
|---|---|
frozen | 创建任务时从余额中冻结的金额 |
charged | 任务成功时扣除的金额；结束前和失败的任务为 "0.00" |
refunded | 退回可用余额的金额；结束前为 "0.00" |
billed_seconds | 计费秒数（数字，最多 3 位小数），任务成功后才有，否则为 null |
任务结束后：charged + refunded = frozen。见计费规则。
失败原因
失败任务的 error，例如 { "code": "queue_timeout", "message": "The task did not start within 30 minutes." }。冻结金额总是全额退回。
code | 说明 |
|---|---|
queue_timeout | 排队 30 分钟内未开始生成 |
content_policy | 输入违反使用规范，例如受保护的肖像或受版权保护的内容 |
invalid_request | 模型不接受这组参数 |
generation_failed | 生成失败或超时 |
internal_error | 内部错误，可以重新创建任务 |