创建任务
所有模型共用的创建接口：参数、请求示例、返回和全部错误。
POST
https://api.nanoapi.ai/v1/tasks每次生成都是一个任务。所有模型都用这个接口创建任务，用 model 指定模型；创建后用查询任务或列出任务拿结果，或者等回调。所有响应都是 { code, message, data } 这一层外层，见响应格式。
从可用余额中冻结费用，任务在后台生成，不能取消。接口通常 1–3 秒返回。
参数
下面的参数所有模型都一样；其余参数（例如 mode、video_url、image_urls）因模型而异，见各模型的页面：Genjutsu 1.0。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型，例如 genjutsu-1.0。各模型页面上有写，也可以从 GET /v1/products 的 models 读取 |
num_outputs | integer | 否 | 目前只能是 1（默认） |
webhook_url | string | 否 | 任务成功或失败时通知该地址：https，最长 2048 字符，不能指向内网、回环或保留地址。见回调 |
没传 model 或者模型不存在，返回 400 invalid_request，param 为 "model"；传了模型不支持的参数也返回 400 invalid_request。全部错误见下面的错误。
请求示例
以 Genjutsu 1.0 的动作迁移为例：
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "genjutsu-1.0",
"mode": "motion_control",
"image_urls": ["https://example.com/person.png"],
"video_url": "https://example.com/dance.mp4",
"resolution": "720p",
"webhook_url": "https://example.com/hooks/nanoapi"
}'返回
成功返回 200，data 是精简的任务对象，只有下面这几个字段。参数、结果、耗时等用查询任务拿。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "genjutsu-1.0",
"status": "queued",
"billing": {
"currency": "USD",
"frozen": "4.095",
"charged": "0.00",
"refunded": "0.00",
"billed_seconds": null
},
"error": null,
"created_at": "2026-10-22T08:30:00Z"
}
}data.status | 含义 | 接下来 |
|---|---|---|
queued | 正常：任务在排队，billing.frozen 是已冻结的金额 | 保存 data.id，等回调或用查询任务拿结果 |
failed | 任务建好了，但提交给生成服务时就被拒绝（通常是 content_policy）。冻结金额已全额退回，error 里是原因 | 按 data.error.type 处理，见失败原因 |
错误
请求出错时返回 4xx / 5xx，没有建任务，没有冻结费用。例如余额不够：
{
"code": 402,
"message": "Your available balance is not enough to create this task.",
"error": {
"type": "insufficient_balance",
"param": null,
"details": { "required": "4.095", "available": "3.00" }
},
"request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}程序按 error.type 判断；error.param 是出错的参数，error.details 的字段写在下表里。
error.type | 状态码 | 什么时候出现 | 怎么处理 |
|---|---|---|---|
invalid_request | 400 | 参数不对：没传 model 或模型不存在（param 为 "model"）；必填参数缺失、类型或取值不对，例如 image_urls 不是 1–10 张、resolution 不是 480p / 720p / 1080p；传了这个模型不支持的参数。param 指出是哪个参数 | 按 param 和 message 修正参数。每个模型的参数见它的页面，例如 Genjutsu 1.0 |
invalid_media | 400 | 源视频读不了：链接打不开或已过期、不是公网地址、不是视频，或格式不支持（支持 mp4、mov、webm、mkv）。details.reason 是具体原因（英文） | 换一个能直接下载的视频链接 |
video_too_long | 400 | 源视频超过 30 秒。details.video_duration 是视频时长（秒），details.max_seconds 是上限 | 裁剪到 30 秒以内再创建 |
video_too_short | 400 | replace_object 的源视频不到 4 秒。details.video_duration 是视频时长（秒），details.min_seconds 是下限 | 换一段 4 秒以上的视频 |
invalid_api_key | 401 | 没带 Key、格式不对，或者 Key 不存在、已删除、已重置 | 换一个有效的 Key，见鉴权 |
insufficient_balance | 402 | 可用余额不够冻结这次的费用。details.required 是本次需要的金额，details.available 是你的可用余额；可用余额为 0 时 details.required 为 null | 充值后重新创建 |
account_suspended | 403 | 账号已停用 | 联系 support@nanoapi.ai |
rate_limited | 429 | 创建太频繁：每个账号每 10 秒最多创建 20 个任务，所有 Key 共享（网站试玩也算在内）。不限制同时进行中的任务数 | 等 Retry-After 秒后重试 |
internal_error | 500 | 服务端出错 | 可以，稍后重试 |
service_unavailable | 503 | 暂时算不出价格，没有建任务 | 等 Retry-After 秒（一般 10 秒）后重试 |
源视频打不开、太长或太短时，创建接口直接返回上面的 400，不创建任务也不冻结费用。参考图要到生成时才读取，参考图有问题时任务会创建成功、之后失败（invalid_media），见失败原因。