クイックスタート
5分以内に最初の Photta 画像を生成。
1つのアカウント、1つのAPIキー、5つのシェルコマンド。以下の手順は Photta の公式ドキュメントが推奨する内容と完全に一致しており、ラッパーや SDK、特定のフレームワークを前提としません。
要約
ai.photta.app でサインアップし、Generate API key をクリック、PHOTTA_API_KEY としてエクスポートします。/api/v1/tryon/apparel に POST し、返された生成IDを status が completed になるまで(通常 1.5–4 分) 3秒ごとにポーリングします。
仕組み
ゼロから最初の画像まで5つのコマンド
順番にターミナルに貼り付けてください。各スニペットは自己完結しており、curl と jq のみを使用します。
- 01
ステップ 1
APIキーを生成する
ai.photta.app にサインアップし、開発者ダッシュボードを開きます。Generate API key をクリックします。ライブキーは photta_live_ で始まります。ウォークスルーの以降のステップで読み取れるよう、キーをエクスポートしてください。
# Sign up at ai.photta.app, open the Developers dashboard, # click "Generate API key" and copy it into your env. export PHOTTA_API_KEY="photta_live_xxxxx" export PHOTTA_BASE_URL="https://ai.photta.app/api/v1" - 02
ステップ 2
最初の試着を POST する
商品画像URL、マネキンID、ポーズIDを指定して /api/v1/tryon/apparel を呼び出します。APIは即座に 202 Accepted を返し、data.id に生成IDを含めて返答します。
curl -X POST "$PHOTTA_BASE_URL/tryon/apparel" \ -H "Authorization: Bearer $PHOTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "product_type": "dress", "product_images": ["https://example.com/dress.jpg"], "mannequin_id": "mnq_athena_ts", "pose_id": "pose_standing_front", "resolution": "2K", "aspect_ratio": "3:4" }' # Response: 202 Accepted + data.id (generation ID) - 03
ステップ 3
完了までポーリングする
3秒ごとに /api/v1/tryon/apparel/:id を GET します。通常 1.5–4 分で完了します。ジョブの停滞によるスクリプトのハングを防ぐため、試行回数に上限を設けてください。
# Loop every 3 seconds until status flips to "completed". # Typical completion: 1.5–4 minutes. Max 120 attempts = 6 min. for i in $(seq 1 120); do RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" \ -H "Authorization: Bearer $PHOTTA_API_KEY") STATUS=$(echo "$RESULT" | jq -r '.data.status') [ "$STATUS" = "completed" ] && break [ "$STATUS" = "failed" ] && echo "Job failed" && exit 1 sleep 3 done - 04
ステップ 4
出力を保存する
ステータスが completed になると、data.output_url に生成された画像が入ります。レンダリングをPhottaのCDNに依存しないよう、バイトデータを自社ストレージにダウンロードしてください。
# Pull the final URL out of the response and save the bytes. OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url') curl -sO "$OUTPUT_URL" echo "Saved $(basename "$OUTPUT_URL")" - 05
ステップ 5
失敗時の処理を適切に行う
HTTP ステータスコードで分岐してください:402(クレジット不足)、429(レート制限。Retry-After を遵守)、5xx(一時的なサーバーエラー)。すべてのエラーボディには、プログラムで処理可能な機械可読な error.code が含まれています。
# Surface the common failure modes honestly. case "$STATUS_CODE" in 402) echo "Out of credits — top up at ai.photta.app" ;; 429) echo "Rate limited — honour Retry-After header" ;; 4??) echo "Client error: $(echo "$BODY" | jq '.error.message')" ;; 5??) echo "Server error — retry with backoff" ;; esac
開発者からのよくある質問
開始に関するよくある質問
クイックスタートにはどのくらい時間がかかりますか?+
サインアップ、キー生成、最初の cURL 実行までで約5分。生成自体に 1.5 から 4 分 かかるため、最初のモデル画像を確認するまで実時間で約10分を見込んでください。
試すのにクレジットカードは必要ですか?+
新規アカウントには、支払い前に使用できるトライアルクレジットが付与されています。本番環境に移行する際に、月間クレジット残高が多くレート制限が緩和されたプランを契約してください。
どのエンドポイントから試すべきですか?+
アパレル試着 (/api/v1/tryon/apparel) です。最も広く使われており、ドキュメントも充実しており、他のすべての Photta エンドポイントで再利用されている「非同期 + ポーリング」パターンを網羅しています。これに慣れれば、ジュエリーやゴーストマネキンも同様に扱えます。
ブラウザから実行できますか?+
いいえ。APIキーは必ずサーバーサイドで保持する必要があります。ブラウザに含めると、すべての訪問者にキーが漏洩します。自社のバックエンド(Next.js ルートハンドラー、Express, Flask, Lambda など)に軽量なプロキシを作成し、ブラウザはそのプロキシと通信するようにしてください。