开发者 API

将图像生成接入你的产品。

使用独立 API 密钥,将你的服务端接入 Virtual Try On。创建私密图片、查询任务进度并下载结果,与网站共用账户积分。

你的服务端Virtual Try On API私密图片

将密钥保存在服务端

通过你自己的服务端调用 API,将密钥保存在环境变量中。不要放入浏览器代码、移动应用包、URL、代码仓库或聊天消息。

API 密钥

为每个接入项目创建独立密钥,只选择必要权限并设置有效期。不再需要时及时撤销。密钥无法管理账单或账户资料。

登录后即可创建和管理 API 密钥。

快速开始

1. 创建 API 密钥

在下方登录,为接入项目命名,并在密钥出现时复制。每个账户最多创建五个有效密钥。

2. 提交图像任务

每张新图片使用新的 Idempotency-Key。请求超时后重试时,复用同一个值和完全相同的请求内容,避免重复创建任务与扣费。

POST /api/v1/images
curl https://virtualtryon.art/api/v1/images \
  -H "Authorization: Bearer $VTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-order-1042" \
  -d '{
    "prompt": "Dress the person in the outfit from the second image.",
    "reference_images": [
      "https://your-store.com/person.jpg",
      "https://your-store.com/outfit.jpg"
    ],
    "aspect_ratio": "3:4",
    "resolution": "1K"
  }'
202 Accepted
{
  "id": "YOUR_TASK_ID",
  "status": "queued",
  "credits": 1,
  "status_url": "/api/v1/images/YOUR_TASK_ID",
  "created_at": "2026-11-12T08:00:00.000Z"
}

3. 查询任务结果

使用返回的 id 查询进度。建议每五秒查询一次,在 completed 或 failed 时停止。

GET /api/v1/images/{id}
curl https://virtualtryon.art/api/v1/images/YOUR_TASK_ID \
  -H "Authorization: Bearer $VTO_API_KEY"
200 OK
{
  "id": "YOUR_TASK_ID",
  "status": "completed",
  "images": ["/api/v1/images/YOUR_TASK_ID/content?index=0"]
}

4. 下载图片

任务完成后,使用 API 密钥下载 images 中的地址。请由你的服务端下载,再将文件提供给你的客户。

GET /api/v1/images/{id}/content?index=0
curl "https://virtualtryon.art/api/v1/images/YOUR_TASK_ID/content?index=0" \
  -H "Authorization: Bearer $VTO_API_KEY" \
  --output result.png

服务端 JavaScript

通过环境变量读取密钥,将任务 ID 保存在你的应用中。不要向访客暴露密钥。

Node.js · server only
// Run on your server. Keep VTO_API_KEY in secret storage.
const response = await fetch("https://virtualtryon.art/api/v1/images", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.VTO_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "store-order-1042",
  },
  body: JSON.stringify({
    prompt: "A studio product photo of a linen shirt.",
    aspect_ratio: "3:4",
    resolution: "1K",
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || "Request failed");
// Save result.id, then poll result.status_url from your backend.

身份验证

每个 API 请求(包括结果下载)都必须携带 Authorization: Bearer YOUR_API_KEY。公开 API 不接受网站登录 Cookie 作为授权。

请求字段

字段说明
prompt必填。描述图像或编辑要求,最多 5,000 个字符。
reference_images可选。最多 16 个公开 HTTPS 图片地址,不允许私有网络或 localhost 地址。
aspect_ratio可选,默认 auto。常用值:1:1、3:2、2:3、4:3、3:4、16:9、9:16、21:9。
resolution可选,支持 1K、2K 或 4K,默认 1K。
Idempotency-Key创建任务时必填的请求头。由 1–128 个字母、数字、句点、连字符或下划线组成。

请求只接受这些字段。任务归属、计费与可见性由服务端确定。

限制与积分

每个密钥每分钟允许 60 次请求,包括状态查询和下载。每个账户最多保留 20 个未完成任务。收到 429 时,请按 Retry-After 指定时间等待后重试。

1K 消耗 1 积分,2K 消耗 3 积分,4K 消耗 5 积分。API 与网站共用账户余额,生成任务保持私密。

结果下载与网站遵循相同的水印权益。每日密钥限额统计已接受任务的预留积分,退款后也不会恢复该限额。

1K
1积分
2K
3积分
4K
5积分

响应与错误

提交成功返回 202。状态包括 queued、processing、completed 和 failed。结果地址属于本站,下载时仍需携带 API 密钥。

400请求无效
401密钥缺失、过期或已撤销
402积分不足
403密钥缺少所需权限
404当前账户中未找到任务
409幂等键已用于不同请求
413请求内容过大
415Content-Type 必须为 application/json
422内容不符合使用政策
429请求频率或任务队列达到上限
503服务暂时不可用