機能 · ゴーストマネキン

ゴーストマネキン API ゴーストマネキン商品写真向け

要約

Photta のゴーストマネキン API は、マネキン着用の衣服写真を受け取り、衣服の内部を再構築したインビジブルマネキン画像を返します。3d または flat_lay のスタイルを選択し、POST 送信、3秒ごとにポーリングし、completed 時にダウンロードします。

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

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

POST/api/v1/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
出力例

概要

概要

エンドポイント
POST /api/v1/ghost-mannequin
認証
Bearer APIキー
処理方式
非同期 — ステータスエンドポイントをポーリング
所要時間の目安
1.5–4 min
Credits
2Kで4 credits · 4Kで5 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/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

リクエストパラメータ

product_image

型: string必須

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

型: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

型: string

Which side product_image represents.

= front

値: frontback
angle

型: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

値: straightbackside
style

型: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

値: 3dflat_lay
background_color

型: string

Background color.

= white

値: whitegraybeigeblack
resolution

型: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

値: 2K4K
aspect_ratio

型: string

Output aspect ratio. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

値: 3:41:14:39:1616:9
user_instruction

型: string

Optional free-form note, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

型: string

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. API v1 request fields use snake_case; use brand_label_id.

エラー

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枚を出力

元画像をアップロードし、スタイルを選択、送信、ポーリング、ダウンロード。

  1. ステップ 1

    APIキーを生成

    ゴーストマネキンは他のすべてのPhotta機能と同じ認証情報を使用します — 1つのキー、共通のクレジット残高。

  2. ステップ 2

    元写真をアップロード

    `product_image`に公開URLまたはbase64データURIを渡します。背面ビューがある場合は`back_image`を追加します。画像1枚につき10 MBまでのJPEG、PNG、WebPに対応。

  3. ステップ 3

    ゴーストマネキンのジョブをPOST

    `/api/v1/ghost-mannequin`に`product_image`、`style`（`3d`または`flat_lay`）、および任意の`angle`、`background_color`、`resolution`を指定してPOSTします。完了通知はポーリングのみです — APIはWebhookを送信しません。

  4. ステップ 4

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

    `data.status`が`completed`または`failed`になるまで、3秒ごとにGET `/api/v1/ghost-mannequin/:id`を実行します。一般的な所要時間は1.5〜4分です。

  5. ステップ 5

    ダウンロードして永続化

    出力は、マネキンが除去され衣服の内側が再構築されたPNGです。PDPのゴーストショット、立体感のある商品ギャラリー、平置きインサートに最適です。

Node.js、Python、cURLで共通のエンドポイント

ゴーストマネキンの実装前によくある質問

ゴーストマネキン撮影とは何ですか？

衣服が見えないマネキンに着用されているように見せ、形状と内側の構造を同時に確認できるPDP向けの処理です。従来はスタジオで撮影した複数の写真を合成していましたが、PhottaのAPIならマネキン着用の写真1枚から、1回のAPI呼び出しで生成できます。

ゴーストマネキンの料金はいくらですか？

2Kで4 credits、4Kで5 creditsです — 各ティアともtry-onより1 credit低価格です。失敗したジョブのクレジットは自動的に返金されます。

3Dスタイルと平置きスタイルの違いは何ですか？

`3d`スタイルはマネキンの立体的な体型を維持します — 衣服のボリュームが保たれ、肩や袖が自然に見え、内側が再構築されます。`flat_lay`は衣服をすっきりとした2Dの平置きレイアウトに変換し、統一された正面形状が求められるカプセルコレクションやマーケットプレイスの出品に最適です。

複数の写真をバッチ処理できますか？

はい。元画像の配列を指定して`/api/v1/ghost-mannequin/batch`にPOSTします。レスポンスとしてバッチIDとアイテムごとの生成IDが返されます。全体のステータスは`/api/v1/ghost-mannequin/batch/:id`で、または各アイテムを個別にポーリングします。

内側の縫い目やラベルは維持されますか？

はい — モデルは一般的なテクスチャを推測生成するのではなく、衣服の内側（襟ぐりの内側、袖口の内側、ウエストバンドの裏地）を再構築します。元の写真に見えているタグやプリントラベルも可能な限り維持されます。

結果はどのようにポーリングしますか？

3秒ごとにGET `/api/v1/ghost-mannequin/:id`を実行します。バッチジョブの場合は親エンドポイントをポーリングすると、全体のステータスとアイテムごとの詳細が返されます。

関連機能

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

5分でAPIを試す

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

アカウントを作成してAPIキーを取得ドキュメントを見る
  • 1.5–4 min
  • 2Kで4 credits · 4Kで5 credits
  • 非同期、ポーリング
  • 600 リクエスト/分
  • Bearerキー