接口

任务接口

提交任务、查询任务、列出任务、下载结果，以及防止重复提交。

所有生成都是异步任务：先提交，马上拿到任务 ID，再查询结果或等待回调。

提交任务

POST /v1/tasks

请求体字段：

model（必填）：模型 ID，见模型列表或 GET /v1/models。
input（必填）：生成参数，随模型类型不同，见模型与参数。
route（可选）：这次只用哪些线路、按什么顺序，见线路与路由。
callback_url（可选）：https 地址，任务结束后把结果推送过去，见回调通知。

curl https://janvia.io/v1/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{
    "model": "gpt-image-2",
    "input": { "prompt": "a red fox in the snow", "resolution": "2K" },
    "route": ["fast", "cheap"]
  }'

成功返回 HTTP 202 和任务对象，Location Header 是任务的地址。提交时就出错（参数不对、余额不足等）会直接返回 4xx，不会创建任务，也不扣费。

任务对象

{
  "id": "task_9f2c...",
  "object": "task",
  "model": "gpt-image-2",
  "media_type": "image",
  "status": "completed",
  "progress": 100,
  "input": { "prompt": "a red fox in the snow", "resolution": "2K" },
  "route": "fast",
  "route_name": "Fast",
  "routing": {
    "routes": [
      { "id": "fast", "name": "Fast", "price_usd": 0.06 },
      { "id": "cheap", "name": "Cheap", "price_usd": 0.04 }
    ],
    "source": "request",
    "rule": null
  },
  "output": {
    "files": [
      {
        "type": "image",
        "url": "https://...",
        "mime_type": "image/png",
        "width": 2048,
        "height": 2048
      }
    ]
  },
  "error": null,
  "cost_usd": 0.06,
  "callback": null,
  "created_at": "2026-10-21T08:00:00.000Z",
  "finished_at": "2026-10-21T08:00:12.000Z"
}

status：queued 排队中，in_progress 生成中，completed 已完成，failed 失败。
progress：0–100，上游提供进度时才会变化。
route / route_name：正在或最终服务这个任务的线路。
routing.routes：这个任务可以使用的线路，按尝试顺序排列，带各自的价格。source 说明这个列表从哪来：request（请求里的 route）、rule（密钥的例外规则，rule 是规则序号，从 0 开始）、key（密钥的排序设置）或 default（平台推荐顺序）。
output.files：生成的文件。type 为 image、video 或 audio；图片有 width、height，视频和音频可能有 duration（秒）。
error：失败时的 code 和 message，见错误码。
cost_usd：这个任务的费用，失败时为 0（已退款）。
callback：传了 callback_url 时是回调的送达情况，否则为 null，见回调通知。
input 里的 base64 图片会被截短显示。

查询任务

curl https://janvia.io/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $API_KEY"

建议每 3–5 秒查一次，视频可以更久。只能查自己账户的任务，查不到返回 404 task_not_found。

列出任务

GET /v1/tasks?page=1&limit=20 按创建时间倒序返回你的任务，limit 最大 100：

{ "object": "list", "data": [ ... ], "page": 1, "limit": 20, "total": 132 }

下载结果

output.files[].url 可能是 CDN 地址，也可能是本站的 /v1/tasks/TASK_ID/content/N。两种地址都可以直接下载，不用带密钥：任务 ID 是随机生成、猜不到的，请不要公开分享这些地址。生成的文件建议拿到后保存到你自己的存储。

防止重复提交

网络超时后重试，可能造成同一个任务提交两次、扣两次钱。在 Header 里带上 Idempotency-Key（1–128 个字母、数字或 _ . : -）可以避免：

24 小时内，同一个 key 加同样的请求体，返回同一个任务（HTTP 200，Header Idempotency-Replayed: true），不会再扣费。
同一个 key 换了请求体，返回 409 idempotency_conflict。