機能 · マネキン生成
AIマネキン生成 API 独自のモデル向け
要約
Photta のマネキン生成 API は、指定した属性からフォトリアルな AI モデルを構築して再利用可能なマネキン ID を返します。消費は 4 credits です。アパレル向けと、ジュエリーのクローズアップに最適化した 2 種類のビルダーを用意しています。
- 所要時間の目安: 30-60s
- Credits: 4 credits
- 処理方式: 非同期、ポーリング
- 制限: 600 リクエスト/分
- 認証: Bearerキー
このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/mannequins/generate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/mannequins/generate",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
},
)
data = res.json()["data"] # data["id"], data["status"]概要
概要
- エンドポイント
- POST /api/v1/mannequins/generate
- 認証
- Bearer APIキー
- 処理方式
- 非同期 — ステータスエンドポイントをポーリング
- 所要時間の目安
- 30-60s
- Credits
- 4 credits
- 入力制限
- 1画像あたり最大10 MB、JPEG, PNG, WebP
- 冪等性
- なし
リクエストとレスポンス
リクエスト
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/mannequins/generate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/mannequins/generate",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"category": "Female",
"ethnicity": "east_asian_korean",
"age": "late_20s",
"skin_tone": "light_medium",
"expression": "neutral",
"hair_style": "long_straight",
"hair_color": "black",
"body_type": "slim",
"height": "average"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / Completed
{
"data": {
"id": "mmk_r4s5t6",
"status": "processing",
"category": "Female",
"credits_used": 4,
"created_at": "2026-04-10T14:00:00Z"
},
"request_id": "req_mnk002"
}{
"data": {
"id": "mmk_r4s5t6",
"status": "completed",
"mannequin": {
"id": "mnk_v7w8x9",
"name": "Generated Mannequin",
"gender": "female",
"thumbnail_url": "https://cdn.photta.app/mannequins/mnk_v7w8x9-thumb.jpg"
},
"credits_used": 4,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:00:42Z",
"duration_ms": 42000
},
"request_id": "req_mnk003"
}リクエストパラメータ
category型: string必須
Mannequin category.
値:FemaleMaleGirlChildBoyChildethnicity型: string
Ethnic appearance.
値:east_asian_koreaneast_asian_chinesesoutheast_asiansouth_asiannordicwestern_europeaneastern_europeanmediterraneanafricanafrican_americanmiddle_easternlatin_americanbrazilianmixed_asian_europeanpolynesianage型: string
Age range.
値:early_20slate_20searly_30slate_30s40s50sbaby_1toddler_2_4young_5_7child_8_10preteen_11_13skin_tone型: string
Skin tone.
値:lightlight_mediummediummedium_darkdarkface_shape型: string
Face shape.
値:ovalsquareroundheartoblongdiamondeye_color型: string
Eye color.
値:browndark_brownblackbluegreenhazelgrayambereye_shape型: string
Eye shape.
値:almondroundmonolidhoodedupturneddownturnedexpression型: string
Facial expression.
値:neutralsoft_smilewarm_smileseriousconfidentfriendlyfacial_hair型: string
Facial hair style (Male only).
値:nonelight_stubblemedium_stubbleshort_beardfull_beardgoateemustachemakeup型: string
Makeup style (Female only).
値:naturalminimalsoft_glamprofessionaleditorialhair_style型: string
Hair style. Available options depend on category — use /options endpoint.
hair_color型: string
Hair color.
値:blackdark_brownmedium_brownlight_brownauburnredblondeplatinum_blondegraywhitehair_texture型: string
Hair texture.
値:straightwavycurlycoilybody_type型: string
Body type. Options depend on category — use /options endpoint.
height型: string
Height.
値:shortaveragetallglasses型: string
Glasses.
値:noneeyeglassessunglassesfreckles型: string
Freckles.
値:nonelightprominentpiercings型: string
Piercings.
値:noneearnosemultiple
エラー
- 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を送信しません。
属性を入力し、再利用可能なモデルを出力
オプションの確認、属性の選択、リクエスト送信、ポーリングを経て、取得した ID を再利用します。
ステップ 1
API キーの生成
マネキン生成では、他のすべての Photta 機能と同じ認証情報およびクレジット残高を使用します。
ステップ 2
オプションカタログの確認
GET `/api/v1/mannequins/generate/options` は、カテゴリごとに異なる `hair_style` や `body_type` のリストを含め、受け入れ可能なすべての値を返します。enum 値をハードコードせず、このレスポンスに基づいてフォームを構築してください。
ステップ 3
マネキン生成の POST リクエスト
`category`(`Female`、`Male`、`GirlChild`、`BoyChild`)に加え、17 種類のオプション属性(人種、年齢、肌のトーン、顔や目の形、表情、髭、メイク、髪型、体型、身長、メガネ、そばかす、ピアス)を指定して POST `/api/v1/mannequins/generate` を実行します。
ステップ 4
ジョブが完了するまでポーリング
`data.status` が `completed` または `failed` になるまで、3 秒ごとに GET `/api/v1/mannequins/generate/:id` を実行します。一般的な完了時間は 30 〜 60 秒です。
ステップ 5
マネキンの再利用
完了したレスポンスボディには、固有の ID を持つ `mannequin` オブジェクトが含まれます。その ID を以降の try-on やアイウェアのジョブで `mannequin_id` として渡すことで、すべてのカットで同一の顔を維持できます。
Node.js、Python、cURL による同一 endpoint の実装例
Node.js
Node.jsでのAIマネキン生成 API
ネイティブのfetchを使用してNode.jsバックエンドからPhottaのaIマネキン生成 APIを呼び出します。SDKは不要です。キーを保存し、ジョブを送信して、結果をポーリングするだけです。
読むPython
Python での AIマネキン生成 API
requests ライブラリを使用して Python で Photta の aIマネキン生成 API を呼び出します。30行のラッパーで、httpx による非同期対応も可能であり、Django、FastAPI、Celery で動作します。
読むcURL
cURLによるAIマネキン生成 API
cURLを使用してシェルから直接PhottaのaIマネキン生成 APIを呼び出します。送信、ポーリング、ダウンロード — すべてのスニペットはスクリプトパイプライン向けにjqと連携可能です。
読む
モデル生成に関して開発者からよくある質問
AIマネキンとは何ですか?
キャスティングを行う代わりに、外見の属性を指定して生成されるモデルです。ID として返却されるため、カタログ内のあらゆる衣服に同一の顔、髪型、体型を適用できます。
マネキンの生成コストはいくらですか?
アパレルビルダー、ジュエリービルダーともに 4 credits です。作成済みのマネキンを以降の撮影で再利用する際に追加コストは発生しません — 課金対象は try-on であり、モデル自体ではありません。
どの属性を設定できますか?
`category` は必須です。その他はすべて任意となります:人種、年齢、肌のトーン、顔の形、目の色と形、表情、髭、メイク、髪型・色・質感、体型、身長、メガネ、そばかす、ピアス。指定可能な値はオプション endpoint から確認できます。
ジュエリービルダーは何に使用しますか?
POST `/api/v1/mannequins/jewelry/generate` は、ジュエリーのクローズアップ撮影に特化したモデルを構築します。全身の属性ではなく `jewelry_type`、`shot_type`、`camera_angle`、`background`、`lighting` を受け取るため、首元、耳、手元が至近距離で正確に描写されます。
同じモデルを複数の撮影で再利用できますか?
はい — それがこの endpoint の目的です。生成されたマネキン ID は、アパレル try-on、ジュエリー try-on、アイウェアスタジオで `mannequin_id` として指定できます。
結果をポーリングするにはどうすればよいですか?
`data.status` が `completed` または `failed` になるまで、3 秒ごとに GET `/api/v1/mannequins/generate/:id` を実行します。ジュエリービルダーは独自のステータスパスをポーリングします。
関連機能
機能一覧
バーチャルtry-on API アパレル向け
AIマネキンにアパレルを着せるREST API。非同期処理、生成時間は1.5〜4分、2Kで5クレジット、4Kで6クレジット。cURL、Node.js、Pythonのサンプルコードあり。
エンドポイントを見る機能一覧
ジュエリー try-on API ネックレス、リング、ブレスレット、イヤリングに対応
REST 経由でネックレス、指輪、ブレスレット、イヤリングを AI モデルに配置。2K で 5 credits、クローズアップマネキンを内蔵、Photta のドキュメントに基づく反射を考慮したレンダリング。
エンドポイントを見る実装
アプリ向けのバーチャル try-on 機能を構築する
Photta API を使ったバーチャル try-on 機能リリースのためのエンドツーエンド実装レシピ:アップロード、ジョブ送信、ワーカーからのポーリング、結果のレンダリング。TypeScript + サーバー専用パターン。
エンドポイントを見る比較
Photta vs Fitroom — ファッションAPIを用途に合わせて選定
PhottaとFitroomのエンドポイント、呼び出しごとのcreditsコスト、料金体系、統合性を比較。各サイトから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スニペットを貼り付ければ、コーヒーが淹れ終わる前に最初のモデル着用画像が手に入ります。
- 30-60s
- 4 credits
- 非同期、ポーリング
- 600 リクエスト/分
- Bearerキー