cURL · バーチャル試着 API

cURL でのバーチャル試着 API

API を理解する最短の方法は、シェルから呼び出すことです。Photta のドキュメントは cURL 優先で設計されており、このページのすべての手順はターミナル単体で実行可能です。Node や Python は不要です。

要約

`PHOTTA_API_KEY` をエクスポートし、適切な JSON ボディで `https://ai.photta.app/api/v1/tryon/apparel` に POST します。生成IDを取得し、`data.status` が `completed` になるまで(通常 1.5–4 分) 3秒ごとに `curl … /tryon/apparel/:id` をループ実行します。`jq` を使って最終レスポンスから出力URLを抽出します。

更新日 · 2026-04-19

最初のリクエスト

cURLNode.jsPythoncURL
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -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"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done

期待される結果

Typical completion

1.5–4min

2K / 4K credits

5 / 7

Aspect ratios

5

Product types

6

仕組み

cURL でのバーチャル試着 API

5つのシェルコマンド、curl と jq 以外の依存関係なし。

  1. 01

    ステップ 1

    サインアップしてキーを生成する

    ai.photta.app にアクセスし、Developers タブを開いて Generate API key をクリックします。ライブキーは `photta_live_` で始まります。

  2. 02

    ステップ 2

    キーをエクスポートする

    `export PHOTTA_API_KEY="photta_live_xxx"` をシェルプロファイルや `.envrc` ファイルに記述し、以降の curl コマンドが自動的にキーを読み込めるようにします。

  3. 03

    ステップ 3

    ベースURLを固定する

    `export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"` と設定することで、curl コマンドを短く保ち、将来サンドボックス用URLが提供された際にも簡単に切り替えられます。

  4. 04

    ステップ 4

    送信とポーリング

    `$PHOTTA_BASE_URL/tryon/apparel` に POST してIDを取得し、`curl $PHOTTA_BASE_URL/tryon/apparel/$ID` を3秒ごとにループ実行します。レスポンスを jq にパイプして `.data.status` を抽出します。

  5. 05

    ステップ 5

    結果を保存する

    ジョブ完了後、jq で `.data.output_url` を取得し、`curl -o` でバイトデータをローカルストレージに保存します。これで次のパイプライン処理の準備が整います。

エンドツーエンドのコード

Copy, paste, done.

Four snippets — install prerequisites, wrap the REST call, submit + poll, then handle the errors that actually happen in production.

01cURL is already installed on macOS, Linux, WSL and modern Windows
bash
# Verify curl is available
curl --version

# Export your API key so the rest of the calls can reference it
export PHOTTA_API_KEY="photta_live_xxxxx"
02Set the base URL + auth header once
bash
# Pin the base URL in a shell variable so every call is a one-liner.
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"

# Reusable auth header — every request needs it.
AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
03Submit and poll in one script
bash
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -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"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done
04Read the status code + error body instead of silently failing
bash
# -w pulls out the HTTP status without polluting the JSON body.
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{ "product_type": "dress" }')

BODY=$(echo "$RESPONSE" | sed '$d')
STATUS=$(echo "$RESPONSE" | tail -1)

case "$STATUS" in
  200|202)
    echo "$BODY" | jq '.data' ;;
  402)
    echo "Out of credits" ; echo "$BODY" | jq '.error' ;;
  429)
    RETRY=$(echo "$BODY" | jq -r '.error.retry_after')
    echo "Rate limited — retry in ${RETRY}s" ;;
  *)
    echo "Error $STATUS" ; echo "$BODY" | jq '.error' ;;
esac

この構成の理由

API の検証に cURL が依然として最速である理由

  • Zero install — cURL ships with every major OS
  • Pairs with `jq` for scripted pipelines (CI, cron, bash hooks)
  • Ideal for smoke-testing endpoints before wiring them into code
  • All code in this page copy-pastes into any POSIX shell

対象外の機能

Honest caveats

  • cURL's polling loop blocks your terminal — move to Node/Python for parallel workers
  • No streaming parser for the result; you fetch the final URL when the job is done
  • Windows Command Prompt users should run WSL or PowerShell's curl.exe wrapper

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

Questions other developers ask

Photta の CLI ツールはありますか?+

まだありませんが、cURL と 15行ほどの bash ラッパーでほぼ代用可能です。すべての言語でサブプロセスを実行でき、シェルが CI パイプラインの共通言語であるため、ドキュメントでは cURL 優先の例を重視しています。

API を使うのに jq は必要ですか?+

必須ではありませんが、スクリプト化には非常に便利です。jq を使えば、JSON レスポンスから手動解析なしで `.data.id`, `.data.status`, `.data.output_url` を抽出できます。macOS なら `brew install jq`、Debian/Ubuntu なら `apt install jq` でインストールできます。

curl での認証方法は?+

`-H "Authorization: Bearer $PHOTTA_API_KEY"` をすべてのリクエストに追加します。キーは環境変数に保持し、コミットするスクリプト内に直接記述しないでください。`curl --oauth2-bearer` も動作しますが、明示的なヘッダー形式の方がドキュメントやログで明確です。

cURL ベースのスクリプトを本番で使用できますか?+

単発のバッチ処理や cron ジョブであれば、多くのチームがこの方法でカタログ更新を行っています。長期運用のアプリケーションでは、エラー処理、リトライ、可観測性の観点から、プログラミング言語を使用する方が望ましいです。このページの cURL の例は、Node や Python に移行した後もリクエスト形式の確認に役立ちます。

bash ループでポーリングするには?+

`for i in $(seq 1 120); do … ; sleep 3; done` を使用し、ループ内でステータスチェックを行います。`.data.status` が `completed` または `failed` になったら break します。このページのコード例には、ジョブの停滞を防ぐための上限設定を含む正確なパターンを掲載しています。

curl でエラーレスポンスを確認するには?+

`curl -w "\n%{http_code}"` を使用して、JSON ボディと一緒に HTTP ステータスコードを取得します。ステータスに応じて分岐してください:402(クレジット不足)、429(レート制限。Retry-After を遵守)、5xx(一時的なサーバーエラー)。エラーボディには常に `error.code` と `error.message` フィールドが含まれます。

cURL · バーチャル試着 API

アカウントを作成してAPIキーを取得

`PHOTTA_API_KEY` をエクスポートし、適切な JSON ボディで `https://ai.photta.app/api/v1/tryon/apparel` に POST します。生成IDを取得し、`data.status` が `completed` になるまで(通常 1.5–4 分) 3秒ごとに `curl … /tryon/apparel/:id` をループ実行します。`jq` を使って最終レスポンスから出力URLを抽出します。

cURL 用バーチャル試着 API — Photta | Photta