機能 · ジュエリー

ジュエリー try-on API ネックレス、リング、ブレスレット、イヤリングに対応

要約

Photta のジュエリー try-on API は、ジュエリー写真、jewelry_type(necklace、ring、bracelet、または earrings)、マネキンIDを受け取り、モデルが着用したクローズアップ写真を返します。POST を送信し、3秒ごとにポーリングして、ステータスが completed になったらダウンロードします。

  • 所要時間の目安: 1.5–4 min
  • Credits: 2Kで5 credits · 4Kで6 credits
  • 処理方式: 非同期、ポーリング
  • 制限: 600 リクエスト/分
  • 認証: Bearerキー

このページに記載されている数値はすべて以下に基づきます: 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
入力制限
1画像あたり最大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 / Completed

{
  "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 secondsが含まれます
  • 1画像あたり最大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。1つのキーがすべてのエンドポイントで機能し、1つの credit 残高ですべての機能をカバーします。

  2. ステップ 2

    クローズアップマネキンを選択する

    ジュエリーマネキンの一覧を取得するか、`POST /api/v1/mannequins/jewelry` で独自マネキンをアップロードします — Photta は微小な金属や石向けに肌の質感を調整した専用のクローズアップマネキンセットを提供しています。

  3. ステップ 3

    ジュエリージョブをPOSTする

    `jewelry_image`、`jewelry_type`、`mannequin_id`、および任意の `background`、`resolution`、`aspect_ratio` を指定して `/api/v1/tryon/jewelry` に POST します。サービスがジュエリーのカテゴリに応じて配置を自動スケーリングします。

  4. ステップ 4

    ジョブが完了するまでポーリングする

    3秒ごとに GET `/api/v1/tryon/jewelry/:id` を実行します。レスポンスの形式はアパレルと同一です — `data.status`、`data.output_url`、`data.thumbnail_url`。

  5. ステップ 5

    ダウンロードして永続化する

    PDPのサムネイルにはタイトクロップの 1:1 が最適で、エディトリアルにはより広いアスペクト比が適しています。CDNへの直リンクではなく、バイトデータを自身で保存してください。

ジュエリー try-on の本番導入前に開発者が抱く疑問

サポートされているジュエリーの種類は?

明示的な4つのカテゴリ:necklace、ring、bracelet、earrings。各カテゴリには専用のクローズアップマネキンセットと、その形状に合わせた配置ヒューリスティックが用意されています。リングやイヤリングには 1:1 のアスペクト比が最も効果的で、ネックレスは 3:4 が適しています。

ジュエリー try-on のコストは?

アパレルと同じです:2K で 5 credits、4K で 6 credits。失敗したジョブは自動的に返金されます。クローズアップマネキンライブラリに追加料金はありません。

ジュエリーエンドポイントはアパレルとどう違いますか?

同じ認証、同じポーリングパターン、同じレスポンス構造です — 相違点はリクエストボディにあります。`product_type` と `product_images` の代わりに `jewelry_type` と `jewelry_image` を送信し、ジュエリーカテゴリでフィルタリングされたマネキンを選択します。それ以外(2K/4K、アスペクト比、credits)はすべて共通です。

独自のジュエリーモデルをアップロードできますか?

はい — `POST /api/v1/mannequins/jewelry` でカスタムのクローズアップ参照画像を受け付け、`POST /api/v1/mannequins/jewelry/generate` でオプションから新しいモデルを生成できます。どちらも try-on リクエストに再利用できるIDを返します。

反射する金属や宝石はどのように処理されますか?

クローズアップパイプラインは、鏡面ハイライトと微細なジオメトリに関するメタデータを保持します。ゴールド、シルバー、鏡面研磨されたプラチナは、汎用の try-on パイプラインで発生するようなゴーストや色のにじみなしで正確にレンダリングされます。最良の結果を得るには、極めてクリーンなスタジオ背景を推奨します。

結果はどのようにポーリングすればよいですか?

3〜5秒ごとに GET `/api/v1/tryon/jewelry/:id` を実行します。アパレルと同じステータスライフサイクルです:`processing` → `completed` または `failed`。大半のジョブは 1.5 〜 4 分の範囲で完了します。

関連機能

このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み

5分でAPIを試す

Photta APIキーを生成し、上記のcURLスニペットを貼り付ければ、コーヒーが淹れ終わる前に最初のモデル着用画像が手に入ります。

  • 1.5–4 min
  • 2Kで5 credits · 4Kで6 credits
  • 非同期、ポーリング
  • 600 リクエスト/分
  • Bearerキー