能力 · 首饰

首饰试穿 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 文档 · 已验证

POST/api/v1/tryon/jewelry
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')
A necklace rendered on an AI model by the jewelry try-on API
示例输出

概览

概览

端点
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')

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"
}

请求参数

jewelry_image

类型: string必填

URL or base64 data URI of the jewelry product image.

jewelry_type

类型: string必填

Type of jewelry.

取值: necklaceearringsbraceletring
mannequin_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

取值: 2K4K
aspect_ratio

类型: string

Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.

= 3:4

取值: 3:41:14:39:1616:9
user_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.

错误

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. 步骤 1

    生成 API 密钥

    流程与服装相同 —— ai.photta.app → Developers → Generate API key。一个密钥通用所有 endpoint;一个 credit 余额覆盖所有 capability。

  2. 步骤 2

    挑选特写模特

    列出珠宝模特,或使用 `POST /api/v1/mannequins/jewelry` 上传自定义模特 —— Photta 提供专用的特写模特库,其皮肤纹理针对微小金属和宝石进行了专属调优。

  3. 步骤 3

    POST 提交珠宝任务

    向 `/api/v1/tryon/jewelry` 发送 POST 请求,携带 `jewelry_image`、`jewelry_type`、`mannequin_id` 以及可选的 `background`、`resolution` 和 `aspect_ratio`。服务会自动根据珠宝品类缩放并调整佩戴位置。

  4. 步骤 4

    轮询直至任务完成

    每 3 秒发起一次 GET `/api/v1/tryon/jewelry/:id` 请求。响应格式与服装完全一致 —— `data.status`、`data.output_url`、`data.thumbnail_url`。

  5. 步骤 5

    下载并持久化存储

    紧凑裁剪的 1:1 比例最适合商品详情页(PDP)缩略图;更宽的宽高比适合社论画册风格。请自行存储图片字节,避免对 CDN 进行热链引用(hot-linking)。

开发者上线珠宝 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

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

五分钟内上手试用 API

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

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