能力 · 首饰
首饰试穿 API 适用于项链、戒指、手链和耳环
一句话总结
Photta 首饰试穿 API 接收首饰图片、jewelry_type(necklace、ring、bracelet 或 earrings)以及模特 ID,返回特写模特上身图。POST 提交,每 3 秒轮询一次,status 为 completed 时下载结果。
- 常规耗时: 1.5–4 min
- Credits: 2K 分辨率 5 credits · 4K 分辨率 6 credits
- 处理方式: 异步,轮询
- 限制: 600 次请求/分钟
- 身份验证: Bearer key
本页所有数据均来自 Photta API 文档 · 已验证
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
},
)
data = res.json()["data"] # data["id"], data["status"]
概览
概览
- 端点
- POST /api/v1/tryon/jewelry
- 身份验证
- 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/jewelry \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / 已完成
{
"data": {
"id": "jwl_a1b2c3",
"status": "processing",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z"
},
"request_id": "req_jwl001"
}{
"data": {
"id": "jwl_a1b2c3",
"status": "completed",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/jwl_a1b2c3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/jwl_a1b2c3-thumb.jpg",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:01:10Z",
"duration_ms": 70000
},
"request_id": "req_jwl002"
}请求参数
jewelry_image类型: string必填
URL or base64 data URI of the jewelry product image.
jewelry_type类型: string必填
Type of jewelry.
取值:necklaceearringsbraceletringmannequin_id类型: string必填
ID of the mannequin. Must be jewelry-compatible and have a matching close-up view for the given jewelry_type. Use GET /api/v1/mannequins?jewelry_type=necklace to find compatible mannequins.
background类型: string
Optional. Pass a URL or base64 data URI to use a reference photo as the scene; pass any other string to use it as a free-form text description (e.g. "soft window light on dark velvet"). When omitted, the original mannequin backdrop is preserved.
resolution类型: string
Output resolution. "2K" costs 5 credits per image; "4K" costs 6 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. 4K cannot be combined with aspect_ratio 1:1 (returns 400).
= 2K
取值:2K4Kaspect_ratio类型: string
Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.
= 3:4
取值:3:41:14:39:1616:9user_instruction类型: string
Free-form refinement, e.g. "make the pendant 10% smaller", "keep the clasp visible at the back of the neck". Capped at 400 characters server-side; longer strings are silently truncated. Requests to change the jewelry's size, scale, or proportions are honored and take priority; any other instruction applies only where it does not conflict with reproducing the jewelry exactly from the reference image. Not a determinism or seed control.
错误
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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 密钥
流程与服装相同 —— ai.photta.app → Developers → Generate API key。一个密钥通用所有 endpoint;一个 credit 余额覆盖所有 capability。
步骤 2
挑选特写模特
列出珠宝模特,或使用 `POST /api/v1/mannequins/jewelry` 上传自定义模特 —— Photta 提供专用的特写模特库,其皮肤纹理针对微小金属和宝石进行了专属调优。
步骤 3
POST 提交珠宝任务
向 `/api/v1/tryon/jewelry` 发送 POST 请求,携带 `jewelry_image`、`jewelry_type`、`mannequin_id` 以及可选的 `background`、`resolution` 和 `aspect_ratio`。服务会自动根据珠宝品类缩放并调整佩戴位置。
步骤 4
轮询直至任务完成
每 3 秒发起一次 GET `/api/v1/tryon/jewelry/:id` 请求。响应格式与服装完全一致 —— `data.status`、`data.output_url`、`data.thumbnail_url`。
步骤 5
下载并持久化存储
紧凑裁剪的 1:1 比例最适合商品详情页(PDP)缩略图;更宽的宽高比适合社论画册风格。请自行存储图片字节,避免对 CDN 进行热链引用(hot-linking)。
Node.js、Python 和 cURL 下的同一 endpoint
Node.js
在 Node.js 中使用 首饰试穿 API
在 Node.js 后端中使用原生 fetch 调用 Photta 的 首饰试穿 API。无需 SDK:存储你的 key、提交任务、轮询获取结果即可。
阅读Python
Python 中的 首饰试穿 API
在 Python 中使用 requests 库调用 Photta 的 首饰试穿 API。三十行包装函数,通过 httpx 具备异步亲和性,可在 Django、FastAPI 和 Celery 中开箱即用。
阅读cURL
通过 cURL 调用 首饰试穿 API
直接在终端中使用 cURL 调用 Photta 的 首饰试穿 API。提交、轮询、下载——每个代码片段均可搭配 jq 用于自动化流水线脚本。
阅读
开发者上线珠宝 try-on 前常问的问题
支持哪些珠宝类型?
四种明确类别:necklace、ring、bracelet、earrings。每个类别都有专属的特写模特库,以及针对该形态调优的佩戴启发式算法。戒指和耳环在 1:1 比例下效果最佳;项链在 3:4 比例下呈现更佳。
珠宝 try-on 的费用是多少?
与服装相同:2K 分辨率 5 credits,4K 分辨率 6 credits。失败的任务会自动退款。使用特写模特库无额外费用。
珠宝 endpoint 与服装有何不同?
相同的鉴权方式、相同的轮询模式、相同的响应结构 —— 区别仅在于请求体。您需要传递 `jewelry_type` 和 `jewelry_image`,而非 `product_type` 和 `product_images`,并且选择按珠宝类别筛选的模特。其他所有配置(2K/4K、宽高比、credits)均通用。
我可以上传自己的珠宝模特吗?
可以 —— `POST /api/v1/mannequins/jewelry` 接收自定义特写参考图,`POST /api/v1/mannequins/jewelry/generate` 可根据选项生成新模特。两者均会返回一个 ID,供您传入 try-on 请求中。
它是如何处理反光金属和宝石的?
特写处理管线包含高光反射与微观几何结构的元数据。黄金、白银和镜面抛光铂金均能正确渲染,不会出现通用 try-on 管线常有的重影或色散涂抹。建议使用极简纯净的棚拍背景以获得最佳效果。
如何轮询获取结果?
每 3 到 5 秒发起一次 GET `/api/v1/tryon/jewelry/:id` 请求。状态生命周期与服装相同:`processing` → `completed` 或 `failed`。绝大多数任务在 1.5 到 4 分钟的窗口期内完成。
相关 capability
功能特性
虚拟 try-on API 适用于服装
将服装穿在 AI 模特身上的 REST API。异步处理,1.5–4 分钟生成耗时,2K 分辨率 5 credits,4K 分辨率 6 credits。提供 cURL、Node.js 与 Python 示例代码。
查看 endpoint功能特性
幽灵模特 API 适用于镂空模特商品图
AI 幽灵模特 endpoint。从服装照片中移除模特,完整保留内部细节。支持 3D 或平铺效果,支持批量处理,2K 分辨率 4 credits。
查看 endpoint构建
构建 AI 商品摄影服务
创始人将 Photta 虚拟 try-on API 作为白标 SaaS 转售的实战指南:租户 key、批量扇出、按 credit 计费以及 SLA 现实考量。
查看 endpoint对比
Photta vs FASHN — 时尚 AI API 横向对比
Photta 与 FASHN 全方位对比:endpoint、credits 定价、方案层级、并发限制。数据均来自两家公司于 2026-04-19 的公开定价页面。绝无虚构数字。
查看 endpoint对比
Photta vs Ayna —— 开发者 API 与 Shopify 优先的工作室套件对比
Photta 与 Ayna 对比:三个 REST endpoint 对比以 Shopify 为核心的 Studio 配合 API。两者各有优势。数据于 2026-04-19 采集自双方官网。
查看 endpoint快速开始
5 分钟内生成第一张 Photta 图像。
注册、生成 API 密钥、运行第一个 cURL 调用、轮询直至完成、持久化保存结果。共五个步骤,端到端完整记录。
查看 endpoint参考
Photta API 错误
Photta API 错误类型的完整列表及其状态码、错误响应体的结构,以及哪些失败情况值得重试。
查看 endpoint参考
Photta API 速率限制
Photta API 的速率限制、时间窗口、Retry-After 请求头、轮询间隔以及各套餐的并发上限,均取自官方 API 文档。
查看 endpoint
本页所有数据均来自 Photta API 文档 · 已验证
五分钟内上手试用 API
生成 Photta API key,粘贴上方的 cURL 代码片段,咖啡还没煮好,你的第一张模特实穿图就已经生成完毕。
- 1.5–4 min
- 2K 分辨率 5 credits · 4K 分辨率 6 credits
- 异步,轮询
- 600 次请求/分钟
- Bearer key