クイックスタート

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 のみを使用します。

  1. 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"
  2. 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)
  3. 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
  4. 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")"
  5. 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 など)に軽量なプロキシを作成し、ブラウザはそのプロキシと通信するようにしてください。

クイックスタート

5分後には最初の画像が完成しています

Photta API クイックスタート — 5分で最初の画像を生成 | Photta