機能 · マネキン生成

AIマネキン生成 API 独自のモデル向け

要約

Photta のマネキン生成 API は、指定した属性からフォトリアルな AI モデルを構築して再利用可能なマネキン ID を返します。消費は 4 credits です。アパレル向けと、ジュエリーのクローズアップに最適化した 2 種類のビルダーを用意しています。

  • 所要時間の目安: 30-60s
  • Credits: 4 credits
  • 処理方式: 非同期、ポーリング
  • 制限: 600 リクエスト/分
  • 認証: Bearerキー

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

POST/api/v1/mannequins/generate
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')

概要

概要

エンドポイント
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')

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"
}

リクエストパラメータ

category

型: string必須

Mannequin category.

値: FemaleMaleGirlChildBoyChild
ethnicity

型: string

Ethnic appearance.

値: east_asian_koreaneast_asian_chinesesoutheast_asiansouth_asiannordicwestern_europeaneastern_europeanmediterraneanafricanafrican_americanmiddle_easternlatin_americanbrazilianmixed_asian_europeanpolynesian
age

型: string

Age range.

値: early_20slate_20searly_30slate_30s40s50sbaby_1toddler_2_4young_5_7child_8_10preteen_11_13
skin_tone

型: string

Skin tone.

値: lightlight_mediummediummedium_darkdark
face_shape

型: string

Face shape.

値: ovalsquareroundheartoblongdiamond
eye_color

型: string

Eye color.

値: browndark_brownblackbluegreenhazelgrayamber
eye_shape

型: string

Eye shape.

値: almondroundmonolidhoodedupturneddownturned
expression

型: string

Facial expression.

値: neutralsoft_smilewarm_smileseriousconfidentfriendly
facial_hair

型: string

Facial hair style (Male only).

値: nonelight_stubblemedium_stubbleshort_beardfull_beardgoateemustache
makeup

型: string

Makeup style (Female only).

値: naturalminimalsoft_glamprofessionaleditorial
hair_style

型: string

Hair style. Available options depend on category — use /options endpoint.

hair_color

型: string

Hair color.

値: blackdark_brownmedium_brownlight_brownauburnredblondeplatinum_blondegraywhite
hair_texture

型: string

Hair texture.

値: straightwavycurlycoily
body_type

型: string

Body type. Options depend on category — use /options endpoint.

height

型: string

Height.

値: shortaveragetall
glasses

型: string

Glasses.

値: noneeyeglassessunglasses
freckles

型: string

Freckles.

値: nonelightprominent
piercings

型: string

Piercings.

値: noneearnosemultiple

エラー

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を送信しません。

属性を入力し、再利用可能なモデルを出力

オプションの確認、属性の選択、リクエスト送信、ポーリングを経て、取得した ID を再利用します。

  1. ステップ 1

    API キーの生成

    マネキン生成では、他のすべての Photta 機能と同じ認証情報およびクレジット残高を使用します。

  2. ステップ 2

    オプションカタログの確認

    GET `/api/v1/mannequins/generate/options` は、カテゴリごとに異なる `hair_style` や `body_type` のリストを含め、受け入れ可能なすべての値を返します。enum 値をハードコードせず、このレスポンスに基づいてフォームを構築してください。

  3. ステップ 3

    マネキン生成の POST リクエスト

    `category`(`Female`、`Male`、`GirlChild`、`BoyChild`)に加え、17 種類のオプション属性(人種、年齢、肌のトーン、顔や目の形、表情、髭、メイク、髪型、体型、身長、メガネ、そばかす、ピアス)を指定して POST `/api/v1/mannequins/generate` を実行します。

  4. ステップ 4

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

    `data.status` が `completed` または `failed` になるまで、3 秒ごとに GET `/api/v1/mannequins/generate/:id` を実行します。一般的な完了時間は 30 〜 60 秒です。

  5. ステップ 5

    マネキンの再利用

    完了したレスポンスボディには、固有の ID を持つ `mannequin` オブジェクトが含まれます。その ID を以降の try-on やアイウェアのジョブで `mannequin_id` として渡すことで、すべてのカットで同一の顔を維持できます。

モデル生成に関して開発者からよくある質問

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` を実行します。ジュエリービルダーは独自のステータスパスをポーリングします。

関連機能

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

5分でAPIを試す

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

  • 30-60s
  • 4 credits
  • 非同期、ポーリング
  • 600 リクエスト/分
  • Bearerキー