Capability · 服饰

虚拟 try-on API 适用于服装

一句话总结

Photta 的虚拟 try-on API 接收平铺服装图、模特 ID 和姿势 ID，返回 2K 或 4K 的上身模特大片。POST 提交任务，每隔 3–5 秒轮询 (poll)，当状态为 completed 时即可下载。

常规耗时: 1.5–4 min
Credits: 2K 分辨率 5 credits · 4K 分辨率 6 credits
处理方式: 异步，轮询
限制: 600 次请求/分钟
身份验证: Bearer key

本页所有数据均来自 Photta API 文档 · 已验证 2026-09-10

POST/api/v1/tryon/apparel

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

A garment rendered on an AI model by the apparel try-on API — 示例输出

概览

端点: POST /api/v1/tryon/apparel
身份验证: Bearer API 密钥
处理方式: 异步 — 轮询状态端点
常规耗时: 1.5–4 min
Credits: 2K 分辨率 5 credits · 4K 分辨率 6 credits
宽高比: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
输入限制: 单张图片最大 10 MB；支持 JPEG, PNG, WebP
幂等性: 否

请求与响应

请求

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / 已完成

{
  "data": {
    "id": "try_abc123",
    "status": "processing",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z"
  },
  "request_id": "req_xyz789"
}

{
  "data": {
    "id": "try_abc123",
    "status": "completed",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "output_url": "https://cdn.photta.app/generated/try_abc123.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/try_abc123-thumb.jpg",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z",
    "completed_at": "2026-04-10T12:01:15Z",
    "duration_ms": 75000
  },
  "request_id": "req_abc001"
}

请求参数

字段描述

product_type

类型: string必填

Type of garment.

topbottomtop_and_bottomone_piece

product_images

类型: array[string]必填

Array of image URLs or base64 data URIs. The first entry is the FRONT image and is required. Not used when product_type is "top_and_bottom".

product_back_image

类型: string

Optional URL or base64 data URI for the BACK of the garment. When supplied, the pipeline auto-switches to the back image whenever the selected pose is back-facing (Back / BackCloseUp). Not used when product_type is "top_and_bottom".

top_image

类型: string

Front image of the top garment. Required when product_type is "top_and_bottom".

top_back_image

类型: string

Optional back image of the top garment. Auto-selected on back-facing poses when present.

bottom_image

类型: string

Front image of the bottom garment. Required when product_type is "top_and_bottom".

bottom_back_image

类型: string

Optional back image of the bottom garment. Auto-selected on back-facing poses when present.

mannequin_id

类型: string必填

ID of the mannequin to wear the garment. Use GET /api/v1/mannequins to list available options.

pose_id

类型: string必填

ID of the pose. Use GET /api/v1/poses to list available options. The pose dictates the framing of the output — what's in frame, whether the face/feet are visible, full body vs half body, etc.

background

类型: string

Optional URL or base64 data URI to a background photo. Anything that is not a URL or data: URI is rejected with HTTP 400. When omitted, an editorial neutral backdrop is used.

lock_background

类型: boolean

When true, the supplied background image is reproduced faithfully (locked) instead of being treated as loose inspiration. Requires the background field — returns 400 if set without a background. Echoed back in the response object.

= false

resolution

类型: string

Output resolution. 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

2K4K

aspect_ratio

类型: string

Output aspect ratio. 1:1 cannot be combined with resolution 4K — that combination returns 400.

= 3:4

3:41:14:39:1616:9

body_size

类型: string

Body size of the mannequin.

= M

XSSMLXLXXL

expression

类型: string

Facial expression.

= neutral

neutralhappyserioussmiling

footwear_url

类型: string

URL or base64 of a custom footwear image. The pipeline always stages the footwear when supplied; the prompt's pose-authority block decides whether to render it (poses that don't show feet drop it cleanly).

user_instruction

类型: string

Free-form refinement, e.g. "preserve the seam pattern across the shoulder", "keep the collar contrast strong". Capped at 500 characters server-side; longer strings are silently truncated. Useful for brand-specific details that need an extra nudge.

product_category

类型: string

Optional silhouette anchor for the garment (e.g. "t_shirt", "jeans", "blazer", "midi_dress"). Helps disambiguate the structure of the garment when the silhouette is ambiguous from the photo alone. Used for product_type "top", "bottom", and "one_piece".

top_category

类型: string

Silhouette anchor for the top half. Only valid when product_type is "top_and_bottom".

bottom_category

类型: string

Silhouette anchor for the bottom half. Only valid when product_type is "top_and_bottom".

length

类型: string

Garment length key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=length&garment_type={product_type}.

fit

类型: string

Garment fit key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=fit&garment_type={product_type}.

top_length

类型: string

Top length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=top.

top_fit

类型: string

Top fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=top.

bottom_length

类型: string

Bottom length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=bottom.

bottom_fit

类型: string

Bottom fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=bottom.

错误

状态类型含义

400invalid_request_error: The request is malformed or contains invalid parameters.
401authentication_error: The API key is missing, invalid, or expired.
402insufficient_credits_error: Your account does not have enough credits.
404not_found_error: The requested resource does not exist.
409conflict_error: The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error: Too many requests. Slow down and retry.Retry-After: 30
500api_error: An internal server error occurred. Retry later.

限制

每个 API 密钥每分钟 600 次请求 (固定窗口；各套餐限制相同)
429 响应包含 Retry-After: 30 秒
单张图片最大 10 MB
格式：: JPEG, PNG, WebP
各套餐并发批处理数：: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
仅支持轮询 — API 不发送 Webhook。

五个步骤，一张商品图

挑选模特，提交任务，轮询至完成，下载结果。

步骤 1
生成 API Key
在 ai.photta.app 注册，打开 Developers 标签页，点击 Generate API key。生产环境 Key 以 `photta_live_` 开头。将 Key 写入 `PHOTTA_API_KEY` ——切勿提交到代码库。
步骤 2
挑选模特和姿态
通过 GET `/api/v1/mannequins` 列出可用选项。通过 GET `/api/v1/poses` 获取构图姿态。两个 ID 均需传入试穿请求中。
步骤 3
POST 试穿任务
向 `/api/v1/tryon/apparel` 发送 POST 请求，携带 `product_type`、`product_images`、`mannequin_id`、`pose_id` 以及可选的 `resolution` 和 `aspect_ratio`。API 返回 202 Accepted 及生成任务 ID。
步骤 4
轮询直至任务完成
每 3 秒 GET `/api/v1/tryon/apparel/:id` 一次。当 `data.status` 变为 `completed` 时，payload 会包含 `output_url` 和 `thumbnail_url`。请设置轮询上限，防止任务卡死挂起请求。
步骤 5
下载并持久化存储
从 `output_url` 拉取字节流并转存到你自己的对象存储中。CDN URL 虽然稳定，但生产系统不应依赖它来进行前端渲染。

在 Node.js、Python 和 cURL 中调用相同的 endpoint

开发者上线服装试穿前常问的问题

什么是 Photta 虚拟试穿 API？

一个 REST endpoint，接收平铺商品图和模特 ID，返回逼真的上身效果图。底层采用与 Photta 消费端 App 相同的管线。支持四种商品类型：上装、下装、套装（上装+下装）、连体衣。

每次调用费用是多少？

2K 分辨率单次 5 credits，4K 为 6 credits。Credits 随订阅计划提供，支持随时充值。生成失败不扣除 credits —— 系统会自动退还。

生成一次需要多长时间？

端到端耗时通常为 1.5 到 4 分钟。POST 请求在 1 秒内返回生成任务 ID；在你轮询期间，GPU 渲染任务在后台异步执行。

支持哪些商品类型？

支持四种：`top`、`bottom`、`top_and_bottom`、`one_piece`。每种类型对应的 `product_images` 数据结构不同 —— 例如 `top_and_bottom` 需要同时传入 `top_image` 和 `bottom_image` 的 URL。

可以使用我自己的模特吗？

可以。通过 `POST /api/v1/mannequins` 上传模特照片，或通过 `POST /api/v1/mannequins/generate` 生成新的 AI 模特。返回的 ID 可直接填入试穿请求中。

如何轮询获取结果？

每 3 到 5 秒 GET `/api/v1/tryon/apparel/:id` 一次，直到 `data.status` 变为 `completed` 或 `failed`。请设置尝试次数上限 —— 120 × 3s 足以覆盖文档标明的耗时窗口并留有余量。

五分钟内上手试用 API

生成 Photta API key，粘贴上方的 cURL 代码片段，咖啡还没煮好，你的第一张模特实穿图就已经生成完毕。

创建账户并获取 API Key 阅读文档

1.5–4 min
2K 分辨率 5 credits · 4K 分辨率 6 credits
异步，轮询
600 次请求/分钟
Bearer key

虚拟 try-on API 适用于服装

概览

请求与响应

请求参数

错误

五个步骤，一张商品图

生成 API Key

挑选模特和姿态

POST 试穿任务

轮询直至任务完成

下载并持久化存储

在 Node.js、Python 和 cURL 中调用相同的 endpoint

开发者上线服装试穿前常问的问题

相关能力

五分钟内上手试用 API