機能 · バッチ ゴーストマネキン

バッチ ゴーストマネキン API カタログ全体向け

要約

Phottaのバッチ ゴーストマネキンエンドポイントは、衣服写真の配列を受け取り、バッチIDと画像ごとのアイテムIDを返します。バッチ全体のcreditsが事前に予約され、バッチをポーリングして集約ステータスを取得します。

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

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

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

202 Accepted / Completed

{
  "data": {
    "batch_id": "gmb_x7y8z9",
    "status": "processing",
    "total": 3,
    "completed": 0,
    "failed": 0,
    "items": [
      {
        "id": "gm_p1q2r3",
        "status": "processing"
      },
      {
        "id": "gm_s4t5u6",
        "status": "processing"
      },
      {
        "id": "gm_v7w8x9",
        "status": "processing"
      }
    ],
    "style": "3d",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_reserved": 12,
    "created_at": "2026-04-10T16:05:00Z"
  },
  "request_id": "req_gmb001"
}

リクエストパラメータ

product_images

型: array[object]必須

Array of image objects. Each object contains "image" (URL or base64), optional "back_image", and optional "image_side". API batch caps (5× the dashboard limit): Free/Hobby/Hobby v2 5, Seller/Starter 10, Brand/Pro 25, Studio/Premium 50.

angle

型: string

Applied to all images. "side" reconstructs the side view from each front photo (plus back_image when provided) — see the single-generate endpoint for details.

= straight

値: straightbackside
style

型: string

Applied to all images.

= 3d

値: 3dflat_lay
background_color

型: string

Applied to all images.

= white

値: whitegraybeigeblack
resolution

型: string

Applied to all images. "2K" = 4 credits each. "4K" = 5 credits each. 4K is produced natively in a single generation per item — 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

Applied to all images. 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

Batch-level: one note applied to every item. Optional free-form string, 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

Applied to all images. Brand label UUID returned by the Brand Labels API. 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機能と同じ認証情報と同じクレジット残高を使用します。

  2. ステップ 2

    画像配列を組み立てる

    `product_images` は衣服ごとに1つのオブジェクトを受け取ります: `image`、およびオプションの `back_image` と `image_side`。APIのバッチ上限は、FreeおよびHobbyで5画像、Sellerで10画像、Brandで25画像、Studioで50画像です。

  3. ステップ 3

    バッチをPOST送信

    POST `/api/v1/ghost-mannequin/batch` を実行します。`angle`、`style`、`background_color`、`resolution`、`aspect_ratio` はすべてのアイテムに適用され、`user_instruction` は最大400文字の指示を全体に追加します。最初のアイテムがレンダリングされる前に、バッチ全体のcreditsが予約されます。

  4. ステップ 4

    バッチをポーリング

    3秒ごとに GET `/api/v1/ghost-mannequin/batch/:id` を実行します。レスポンスボディには `total`、`completed`、`failed`、およびアイテムごとの内訳が含まれるため、最後の衣服の処理が完了する前にダウンロードを開始できます。

  5. ステップ 5

    各結果をダウンロード

    完了した各アイテムには、固有の `output_url`、`credits_used`、処理時間が含まれます。失敗したアイテムは予約されたcreditsが返金され、`credits_refunded` に記録されます。

Node.js、Python、cURLでの同一エンドポイントの実装

開発者がバッチを実行する前によく尋ねる質問

バッチエンドポイントは何を提供しますか？

1回のリクエストで衣服写真の配列を受け入れ、バックグラウンドで処理します。何十もの個別ジョブを追跡する代わりに、全体像を把握するためのバッチIDと、写真ごとのアイテムIDを取得できます。

1つのバッチに何枚の画像を入れられますか？

APIのバッチ上限は、FreeおよびHobbyで5画像、Sellerで10画像、Brandで25画像、Studioで50画像です — ダッシュボードの上限の5倍です。プランの許可を超えるバッチは400を返します。

バッチのcreditsはどのように請求されますか？

バッチ全体分が事前に予約されます: 画像数に画像ごとの単価（2Kで4 credits、4Kで5 credits）を掛けた額です。残高が予約額に満たない場合、リクエストは402を返し、レンダリングは一切行われません。

1つのアイテムが失敗した場合はどうなりますか？

バッチの残りの処理は継続されます。バッチのレスポンスボディには `completed` と並んで `failed` が報告され、失敗したアイテムの予約済みcreditsは `credits_refunded` として返金されます。

同時にいくつのバッチを実行できますか？

処理中の同時実行バッチ数はプランごとに制限されています: Freeは1、Hobbyは2、Sellerは3、Brandは4、Studioは6です。上限を超えて送信すると409が返されます — 実行中のバッチが完了するまでポーリングし、その後に再送信してください。

バッチはどのようにポーリングしますか？

集約ステータスを取得するには3秒ごとに GET `/api/v1/ghost-mannequin/batch/:id` を実行し、衣服ごとの詳細が必要な場合は標準のゴーストマネキンステータスパスで個別のアイテムをポーリングします。

関連機能

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

5分でAPIを試す

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

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