クイックスタート

5 分以内に最初の Photta 画像を生成。

要約

ai.photta.app でサインアップし、「Generate API key」をクリックして PHOTTA_API_KEY としてエクスポートします。/api/v1/tryon/apparel に POST し、status が completed に変わるまで（通常は 1.5〜4 分以内）、返された generation ID を 3 秒ごとにポーリングします。

APIキーを取得ドキュメントを見る
  • 認証: Bearerキー
  • 処理方式: 非同期、ポーリング
  • 制限: 600 リクエスト/分

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

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

仕組み

ゼロから最初の画像生成までの 5 つのコマンド

順番にターミナルに貼り付けてください。すべてのスニペットは自己完結しており、curl と jq のみを使用します。

  1. ステップ 1

    API キーを生成する

    ai.photta.app でサインアップし、開発者ダッシュボードを開きます。「Generate API key」をクリックします — 本番用キーは photta_live_ で始まります。このウォークスルーの以降のステップでシェルから読み取れるよう、エクスポートしてください。

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. ステップ 2

    最初の try-on を POST する

    商品画像の URL とマネキン ID を指定して /api/v1/tryon/apparel にリクエストを送信します。API は直ちに 202 Accepted を返し、data.id に generation ID を返します。

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

  3. ステップ 3

    完了するまでポーリングする

    GET /api/v1/tryon/apparel/:id を3秒ごとにポーリングします。通常は1.5〜4分で完了します。ジョブのスタックによってスクリプトが無期限にハングしないよう、試行回数に上限を設定してください。

    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

  4. ステップ 4

    出力を永続化する

    status が completed に変わると、data.output_url にレンダリングされた画像が格納されます。プロダクトの画像表示が Photta の CDN に依存しないよう、バイトデータを自前のストレージにダウンロードしてください。

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. ステップ 5

    失敗時の挙動を適切にハンドリングする

    HTTPステータスコードに応じて分岐させます。credits 不足は 402、レートリミットは 429（Retry-After に従う）、一時的なサーバーエラーは 5xx です。すべてのエラーレスポンスボディには、プログラム側でハンドリング可能な error.code が含まれます。

    case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

開発者からのよくある質問

導入に関するよくある質問

クイックスタートにはどれくらい時間がかかりますか？

サインアップ、キー発行、初回の cURL 実行までで5分です。生成自体に1.5〜4分かかるため、最初の着用画像を確認できるまで実時間で約10分を見込んでください。

試すのにクレジットカードは必要ですか？

新規アカウントには有料利用前に消費できるトライアル credits が付与されます。本番環境への導入準備が整ったら、月間 credits 付与枠の拡大とレートリミット緩和のためのプランに加入してください。

最初にどのエンドポイントを試すべきですか？

アパレル try-on（/api/v1/tryon/apparel）です。最も広く使われており、ドキュメントが最も充実していて、他のすべての Photta エンドポイントで再利用されている非同期＋ポーリングのパターンを網羅しています。この扱いに慣れれば、ジュエリーやゴーストマネキンも同様に動作します。

ブラウザから直接実行できますか？

いいえ。APIキーは必ずサーバーサイドに保持する必要があります。ブラウザにキーを渡すと全訪問者に漏洩します。自前のバックエンド（Next.js ルートハンドラー、Express、Flask、Lambda）に薄いプロキシを設置し、ブラウザからはそのプロキシを経由してリクエストを送ってください。

関連ページ

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

最初の画像生成まで、あと5分です

APIキーを取得API を確認する
  • Bearerキー
  • 非同期、ポーリング
  • 600 リクエスト/分