機能 · ジュエリー
ジュエリー 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ドキュメント · 確認済み
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
- 入力制限
- 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')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 / 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"
}{
"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 secondsが含まれます
- 1画像あたり最大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。1つのキーがすべてのエンドポイントで機能し、1つの credit 残高ですべての機能をカバーします。
ステップ 2
クローズアップマネキンを選択する
ジュエリーマネキンの一覧を取得するか、`POST /api/v1/mannequins/jewelry` で独自マネキンをアップロードします — Photta は微小な金属や石向けに肌の質感を調整した専用のクローズアップマネキンセットを提供しています。
ステップ 3
ジュエリージョブをPOSTする
`jewelry_image`、`jewelry_type`、`mannequin_id`、および任意の `background`、`resolution`、`aspect_ratio` を指定して `/api/v1/tryon/jewelry` に POST します。サービスがジュエリーのカテゴリに応じて配置を自動スケーリングします。
ステップ 4
ジョブが完了するまでポーリングする
3秒ごとに GET `/api/v1/tryon/jewelry/:id` を実行します。レスポンスの形式はアパレルと同一です — `data.status`、`data.output_url`、`data.thumbnail_url`。
ステップ 5
ダウンロードして永続化する
PDPのサムネイルにはタイトクロップの 1:1 が最適で、エディトリアルにはより広いアスペクト比が適しています。CDNへの直リンクではなく、バイトデータを自身で保存してください。
Node.js、Python、cURL で同一のエンドポイント
Node.js
Node.jsでのジュエリー try-on API
ネイティブのfetchを使用してNode.jsバックエンドからPhottaのジュエリー try-on APIを呼び出します。SDKは不要です。キーを保存し、ジョブを送信して、結果をポーリングするだけです。
読むPython
Python での ジュエリー try-on API
requests ライブラリを使用して Python で Photta の ジュエリー try-on API を呼び出します。30行のラッパーで、httpx による非同期対応も可能であり、Django、FastAPI、Celery で動作します。
読むcURL
cURLによるジュエリー try-on API
cURLを使用してシェルから直接Phottaのジュエリー try-on APIを呼び出します。送信、ポーリング、ダウンロード — すべてのスニペットはスクリプトパイプライン向けにjqと連携可能です。
読む
ジュエリー 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 分の範囲で完了します。
関連機能
機能一覧
バーチャルtry-on API アパレル向け
AIマネキンにアパレルを着せるREST API。非同期処理、生成時間は1.5〜4分、2Kで5クレジット、4Kで6クレジット。cURL、Node.js、Pythonのサンプルコードあり。
エンドポイントを見る機能一覧
ゴーストマネキン API ゴーストマネキン商品写真向け
AIゴーストマネキンエンドポイント。衣服写真からマネキンを除去し、内部のディテールを保持します。3Dまたは平置き、バッチ処理、2K で 4 credits。
エンドポイントを見る実装
AI商品撮影サービスを構築する
Phottaのバーチャルtry-on APIをホワイトラベルSaaSとしてリセールするためのファウンダー向けプレイブック:テナントキー、バッチファンアウト、credit単位の請求、SLAの現実。
エンドポイントを見る比較
Photta vs FASHN — ファッションAI APIの徹底比較
PhottaとFASHNの比較:エンドポイント、クレジット料金、プラン階層、同時実行数上限。2026-04-19時点の各社公式価格設定ページから取得。加工された数値はありません。
エンドポイントを見る比較
Photta vs Ayna — 開発者向けAPIか、Shopifyファーストのスタジオか
PhottaとAynaの比較:3つのRESTエンドポイント vs Shopifyファーストのスタジオ+API。双方に強みがあります。2026-04-19に各サイトから取得した情報に基づきます。
エンドポイントを見るクイックスタート
5 分以内に最初の Photta 画像を生成。
サインアップ、API キーの生成、最初の cURL 呼び出しの実行、完了までのポーリング、結果の保存。エンドツーエンドで文書化された 5 つのステップ。
エンドポイントを見るリファレンス
Photta APIのエラー
ステータスコード別のPhotta APIエラータイプ一覧、エラーボディの構造、およびリトライすべき障害。
エンドポイントを見るリファレンス
Photta APIのレートリミット
Photta APIのレートリミット、ウィンドウ幅、Retry-Afterヘッダー、ポーリング間隔、プラン別の同時実行上限など、APIドキュメントに記載された仕様です。
エンドポイントを見る
このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み
5分でAPIを試す
Photta APIキーを生成し、上記のcURLスニペットを貼り付ければ、コーヒーが淹れ終わる前に最初のモデル着用画像が手に入ります。
- 1.5–4 min
- 2Kで5 credits · 4Kで6 credits
- 非同期、ポーリング
- 600 リクエスト/分
- Bearerキー