機能 · アイウェアスタジオ

アイウェア仮想 try-on API メガネおよびサングラス向け

要約

PhottaのアイウェアスタジオAPIは、メガネやサングラスの写真を1枚から完成されたショットへと変換します。商品単体またはモデル着用を選択し、POSTして 3 秒ごとにポーリング、ステータスが completed になったらダウンロード。2Kで 5 credits。

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

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

POST/api/v1/eyewear-studio
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
Sunglasses photographed by the eyewear studio API
出力例

概要

概要

エンドポイント
POST /api/v1/eyewear-studio
認証
Bearer APIキー
処理方式
非同期 — ステータスエンドポイントをポーリング
所要時間の目安
20–60 sec
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/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
    "status": "processing",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-08-01T09:15:00Z"
  },
  "request_id": "req_eyw001"
}

リクエストパラメータ

eyewear_image

型: string必須

The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

mode

型: string

Generation mode: "product-only" — the eyewear alone, styled by sub_tool; "on-model" — the eyewear worn on an AI model's face (requires mannequin_id).

= product-only

値: product-onlyon-model
sub_tool

型: string

Product-only styling: "studio-shot" — clean studio product shot; "flat-lay" — top-down arrangement on a surface; "lifestyle" — the eyewear placed in a real-world scene; "floating" — the frames suspended mid-air. Sending sub_tool with mode "on-model" returns 400.

= studio-shot

値: studio-shotflat-laylifestylefloating
mannequin_id

型: string

Required when mode is "on-model": the AI model whose face wears the eyewear — an id ("mnk_...") from GET /api/v1/eyewear-studio/mannequins. Sending it in product-only mode returns 400.

face_angle

型: string

On-model only: the angle of the model's face.

= front

値: frontthree-quarterside-profile
expression

型: string

On-model only: the model's facial expression.

= neutral

値: neutralsoft-smileseriousconfident
lighting_style

型: string

On-model only: how the portrait is lit.

= soft-diffused

値: soft-diffusedstudionaturaldramatic
frame_fit_style

型: string

On-model only: the overall styling of how the frames are worn.

= casual

値: casualprofessionalfashion-editorialsporty
backdrop

型: string

Studio-shot only: the backdrop behind the eyewear.

= white

値: whitegrayblackgradient
lighting

型: string

Studio-shot only: the lighting setup.

= soft

値: softharddramaticnatural
surface

型: string

Flat-lay only: the surface the eyewear lies on.

= marble

値: marblewoodfabricconcretemetal
arrangement_style

型: string

Flat-lay only: how the composition is arranged.

= minimal

値: minimalsymmetricscatteredlayered
props

型: string

Flat-lay only: complementary props placed around the eyewear.

= none

値: noneplantsaccessoriestech
scene

型: string

Lifestyle only: the real-world setting.

= coffee-shop

値: coffee-shopbeachurban-streetofficepark
mood

型: string

Lifestyle only: the color mood of the scene.

= warm

値: warmcoolvibrantmoody
angle

型: string

Floating only: the camera angle on the suspended frames.

= front

値: frontthree-quartersidetop-down
shadow_style

型: string

Floating only: the shadow cast beneath the frames.

= soft-drop

値: soft-dropnonehard-dropreflection
background_color

型: string

Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.

= white

値: whitegrayblackbeige
background_prompt

型: string

Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.

aspect_ratio

型: string

Output aspect ratio.

= 3:4

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

型: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

値: 2K4K

エラー

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

    モードとスタイリングの選択

    `mode` は `product-only` または `on-model` です。商品単体（`product-only`）は `sub_tool`（`studio-shot`、`flat-lay`、`lifestyle`、または `floating`）を受け取り、それぞれ固有のコントロールを展開します。モデル着用（`on-model`）は `mannequin_id` に加え、`face_angle`、`expression`、`lighting_style`、`frame_fit_style` を受け取ります。

  3. ステップ 3

    アイウェアジョブをPOST

    `/api/v1/eyewear-studio` に `eyewear_image` とスタイリング用フィールドを指定してPOSTします。`background_prompt` は最大 400 文字まで受け付け、`background_color` を上書きします。完了シグナルはポーリングのみで、APIからWebhookは送信されません。

  4. ステップ 4

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

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

  5. ステップ 5

    ダウンロードと永続化

    完了時のレスポンスボディには `output_url` とサムネイルが含まれます。URLは1ジョブの配信先として扱い、恒久的なホスティングではないため、ファイルは自環境で保存してください。

Node.js、Python、cURLにおける同一エンドポイントの実装

アイウェアショットのプロダクション投入前によくある質問

アイウェアスタジオAPIで何ができますか？

メガネやサングラスの商品写真を1枚渡すことで、スタイリングされた写真を返します。スタジオ、平置き、ライフスタイル、フローティングといったフレーム単体の処理、または選択したAIモデルの顔への着用ショットのいずれかを生成できます。

アイウェアショットの利用コストはいくらですか？

2Kで 5 credits、4Kで 6 credits であり、アパレルやジュエリーの try-on と同一です。失敗したジョブのクレジットは自動的に返還されます。

商品単体（product-only）とモデル着用（on-model）の違いは何ですか？

`product-only` はフレーム単体を撮影し、`sub_tool` によって制御されます。`on-model` はAIモデルの顔に着用させ、`mannequin_id`、`face_angle`、`expression`、`lighting_style`、`frame_fit_style` で制御されます。他方のモードに属するフィールドは無視されます。

各サブツールではどのスタイリングオプションが使えますか？

`studio-shot` は `backdrop` と `lighting`、`flat-lay` は `surface`、`arrangement_style`、`props`、`lifestyle` は `scene` と `mood`、`floating` は `angle` と `shadow_style` を受け取ります。これらすべてのフィールドはenumであるため、想定外の値は推測処理されず拒絶されます。

独自のAIモデルを使用できますか？

はい。`mannequin_id` には GET `/api/v1/eyewear-studio/mannequins` から取得した任意のマネキンIDを指定でき、マネキン生成APIで作成したマネキンも同様に使用可能です。

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

`data.status` が `completed` または `failed` になるまで、3秒ごとに GET `/api/v1/eyewear-studio/:id` を実行してください。Webhookはありません。ポーリングが仕様通りの完了シグナルです。

関連機能

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

5分でAPIを試す

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

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