機能 · Workflows
Workflows API 1 回の呼び出し、1 つのプリセット
要約
Photta の workflows API は、商品画像に対して既成のシーンテンプレートを実行します。カタログを取得し、ワークフローの画像スロットとオプションを入力して POST し、返された各アイテムが完了するまでポーリングします。
- 所要時間の目安: 20–60 sec / image
- Credits: 2Kで4 credits · 4Kで5 credits
- 処理方式: 非同期、ポーリング
- 制限: 600 リクエスト/分
- 認証: Bearerキー
このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]概要
概要
- エンドポイント
- POST /api/v1/workflows/{workflow_id}
- 認証
- Bearer APIキー
- 処理方式
- 非同期 — ステータスエンドポイントをポーリング
- 所要時間の目安
- 20–60 sec / image
- Credits
- 2Kで4 credits · 4Kで5 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/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / Completed
{
"data": {
"items": [
{
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
},
{
"id": "wfl_8b2d64f0a1c9573ee4082d6cb95a3f17",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
}
],
"workflow_id": "jewelry-studio-shot",
"workflow_version": 1,
"credits_used": 8
},
"request_id": "req_wfl002"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}リクエストパラメータ
workflow_id型: string必須
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
images型: object必須
Map of image slot id → array of images (https URL or base64 data URI). Slot ids, required flags, and min/max image counts come from the workflow's image_slots in the catalog. Missing entirely, missing a required slot, using an unknown slot, or exceeding a slot's max_images returns 400.
options型: object
Map of option id → choice id, both from the workflow's options in the catalog. Omitted options use their default_choice. Unknown option ids or choice ids return 400, as does sending an option that a filled image slot replaces (see replaces_options).
user_text型: string
Free-text styling/framing request (e.g. "hero shot, slightly angled"). Max 500 characters — excess is silently truncated. It never overrides product fidelity: the product always stays true to your images.
num_images型: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratio型: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
値:3:41:14:39:1616:9resolution型: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
値:2K4K
エラー
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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
API キーを生成
Workflows は、他のすべての Photta 機能と同じ認証情報と同じ credits 残高を使用します。
ステップ 2
ワークフローカタログを一覧取得
GET `/api/v1/workflows` は、7 つのカテゴリにわたる 53 種類のテンプレートを返します。各テンプレートは独自の画像スロット、オプションの enum、デフォルトのアスペクト比を定義しています。`category` で絞り込みが可能です — 未知のカテゴリは無視されず 400 を返します。
ステップ 3
実行リクエストを POST
カタログエントリから取得した `images`(スロット ID から画像へのマップ)と `options`(オプション ID から選択肢 ID へのマップ)を指定して POST `/api/v1/workflows/:workflow_id` を実行します。`user_text` は自由形式のスタイリングリクエストを受け付け、`num_images` は 1 回の呼び出しで 1 から 4 枚の画像を処理します。
ステップ 4
すべてのアイテムをポーリング
202 レスポンスには、リクエストされた画像ごとに 1 つのアイテムが含まれます。各 ID に対して、`data.status` が `completed` または `failed` になるまで 3 秒ごとに GET `/api/v1/workflows/generations/:id` を実行します。通常の完了時間は画像 1 枚あたり 20 から 60 秒です。
ステップ 5
ダウンロードして永続化
完了した各アイテムには独自の `output_url` が含まれます。アイテムは個別に完了するため、残りがレンダリング中であっても最初のアイテムを公開できます。
Node.js、Python、cURL での同一エンドポイント
Node.js
Node.jsでのWorkflows API
ネイティブのfetchを使用してNode.jsバックエンドからPhottaのworkflows APIを呼び出します。SDKは不要です。キーを保存し、ジョブを送信して、結果をポーリングするだけです。
読むPython
Python での Workflows API
requests ライブラリを使用して Python で Photta の workflows API を呼び出します。30行のラッパーで、httpx による非同期対応も可能であり、Django、FastAPI、Celery で動作します。
読むcURL
cURLによるWorkflows API
cURLを使用してシェルから直接Phottaのworkflows APIを呼び出します。送信、ポーリング、ダウンロード — すべてのスニペットはスクリプトパイプライン向けにjqと連携可能です。
読む
ワークフロー実行前にエンジニアからよくある質問
Workflows API とは何ですか?
自社の商品写真に対して実行できる、既成シーンテンプレートのカタログです。プロンプトを組み立てる代わりに、ワークフローを選択し、定義されている画像スロットとオプションを入力します。
ワークフロー実行のコストはいくらですか?
2K で画像 1 枚あたり 4 credits、4K で画像 1 枚あたり 5 credits に `num_images` を掛けた値です。カタログには各ワークフローの最新の価格情報が含まれています — 推測せず、そこから読み取ってください。
ワークフロー ID はどのように見つけますか?
GET `/api/v1/workflows` を実行します。各エントリには、その ID、カテゴリ、画像スロット、オプションが含まれています。`category`(`jewelry`、`product`、`shoe`、`cosmetics`、`food`、`bag`、`watch`)でリストを絞り込みます。
images と options には何を指定しますか?
`images` はカタログエントリのスロット ID を画像(https URL または base64 データ URI)の配列にマッピングします。`options` はオプション ID をそのオプションの選択肢 ID の 1 つにマッピングします。どちらのデータ構造もカタログから提供されるため、新しいワークフローが追加されても既存の連携コードをそのまま維持できます。
1 回の実行で生成できる画像の数は?
`num_images` は 1 から 4 を受け付けます。各画像は個別に生成され、レスポンス内で独自のアイテム ID が付与されるため、1 つが失敗しても他の生成には影響しません。
結果をポーリングするにはどうすればよいですか?
各アイテムを個別にポーリング: 3秒ごとに GET `/api/v1/workflows/generations/:id` を実行します。GET `/api/v1/workflows/generations/list` では、`workflow_id` や `status` でフィルタリングされたページネーション表示を取得できます。
関連機能
機能一覧
バーチャルtry-on API アパレル向け
AIマネキンにアパレルを着せるREST API。非同期処理、生成時間は1.5〜4分、2Kで5クレジット、4Kで6クレジット。cURL、Node.js、Pythonのサンプルコードあり。
エンドポイントを見る機能一覧
ジュエリー try-on API ネックレス、リング、ブレスレット、イヤリングに対応
REST 経由でネックレス、指輪、ブレスレット、イヤリングを AI モデルに配置。2K で 5 credits、クローズアップマネキンを内蔵、Photta のドキュメントに基づく反射を考慮したレンダリング。
エンドポイントを見る実装
AI商品撮影サービスを構築する
Phottaのバーチャルtry-on APIをホワイトラベルSaaSとしてリセールするためのファウンダー向けプレイブック:テナントキー、バッチファンアウト、credit単位の請求、SLAの現実。
エンドポイントを見る比較
Photta vs Ayna — 開発者向けAPIか、Shopifyファーストのスタジオか
PhottaとAynaの比較:3つのRESTエンドポイント vs Shopifyファーストのスタジオ+API。双方に強みがあります。2026-04-19に各サイトから取得した情報に基づきます。
エンドポイントを見るクイックスタート
5 分以内に最初の Photta 画像を生成。
サインアップ、API キーの生成、最初の cURL 呼び出しの実行、完了までのポーリング、結果の保存。エンドツーエンドで文書化された 5 つのステップ。
エンドポイントを見るリファレンス
Photta APIのエラー
ステータスコード別のPhotta APIエラータイプ一覧、エラーボディの構造、およびリトライすべき障害。
エンドポイントを見るリファレンス
Photta APIのレートリミット
Photta APIのレートリミット、ウィンドウ幅、Retry-Afterヘッダー、ポーリング間隔、プラン別の同時実行上限など、APIドキュメントに記載された仕様です。
エンドポイントを見る
このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み
5分でAPIを試す
Photta APIキーを生成し、上記のcURLスニペットを貼り付ければ、コーヒーが淹れ終わる前に最初のモデル着用画像が手に入ります。
- 20–60 sec / image
- 2Kで4 credits · 4Kで5 credits
- 非同期、ポーリング
- 600 リクエスト/分
- Bearerキー