将密钥保存在服务端
通过你自己的服务端调用 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 | 请求内容过大 |
| 415 | Content-Type 必须为 application/json |
| 422 | 内容不符合使用政策 |
| 429 | 请求频率或任务队列达到上限 |
| 503 | 服务暂时不可用 |