Janvia

接口

任务接口

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

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

提交任务

POST /v1/tasks

请求体字段:

  • model(必填):模型 ID,见 模型列表 或 GET /v1/models。
  • input(必填):生成参数,随模型类型不同,见 模型与参数。
  • route(可选):这次只用哪些线路、按什么顺序,见 线路与路由。
  • callback_url(可选):https 地址,任务结束后把结果推送过去,见 回调通知。
  • upload(可选):每个输出文件一个预签名上传地址,文件直接存进你自己的存储,见 上传到你的存储。
curl https://api.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,
  "quote_usd": 0.06,
  "usage": null,
  "callback": null,
  "upload": null,
  "created_at": "2026-10-21T08:00:00.000Z",
  "finished_at": "2026-10-21T08:00:12.000Z"
}
  • status:queued 排队中,in_progress 生成中,completed 已完成,failed 失败。带了 upload 的任务,文件上传完之前都是 in_progress。
  • 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(内容审核拒绝时还有 category),见 错误码。
  • cost_usd:这个任务的费用,失败时为 0(已退款)。按 token 计价的线路在完成时按实际用量结算,可能和 quote_usd 不同。
  • quote_usd:提交时扣的预估价。
  • usage:按 token 计价的线路完成后,上游返回的实际用量:input_text_tokens、input_image_tokens、output_tokens;其他线路为 null。见 计费与退款。
  • callback:传了 callback_url 时是回调的送达情况,否则为 null,见 回调通知。
  • upload:传了 upload 时是文件上传到你存储的情况,否则为 null,见 上传到你的存储。
  • input 里的 base64 图片会被截短显示。

查询任务

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

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

列出任务

GET /v1/tasks 按创建时间倒序返回你的任务。查询参数都是可选的:

  • limit:每次返回几个,1–100,默认 20。
  • status:只要这个状态的任务,queued、in_progress、completed 或 failed。
  • model:只要这个模型的任务。
  • after:上一次返回的最后一个任务的 ID,从它后面接着取。
curl "https://api.janvia.io/v1/tasks?status=completed&limit=50" \
  -H "Authorization: Bearer $API_KEY"
{ "object": "list", "data": [ ... ], "page": 1, "limit": 50, "total": 132, "has_more": true }

has_more 为 true 时还有更早的任务:把 data 里最后一个任务的 ID 作为 after 再请求,直到 has_more 为 false。这样取完全部任务,中途有新任务提交也不会重复或漏掉。带 after 的返回只有 object、data、limit 和 has_more。

也可以用 page(从 1 开始)按页取,返回带总数 total。但翻页时有新任务进来,后面的页会和前面的重复几条,所以要取全部任务时请用 after。

下载结果

output.files[].url 可能是 CDN 地址,也可能是本站的 /v1/tasks/TASK_ID/content/N。两种地址都可以直接下载,不用带密钥:任务 ID 是随机生成、猜不到的,请不要公开分享这些地址。

我们保存的生成文件在任务完成后保留 24 小时,之后删除,链接随之失效,/v1/tasks/TASK_ID/content/N 返回 410。请在 24 小时内下载,或者用 upload 让我们直接上传到你的存储,传过去的文件不受这个期限影响。

防止重复提交

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

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