機能 · Workflows

Workflows API 1 回の呼び出し、1 つのプリセット

要約

Photta の workflows API は、商品画像に対して既成のシーンテンプレートを実行します。カタログを取得し、ワークフローの画像スロットとオプションを入力して POST し、返された各アイテムが完了するまでポーリングします。

  • 所要時間の目安: 20–60 sec / image
  • Credits: 2Kで4 credits · 4Kで5 credits
  • 処理方式: 非同期、ポーリング
  • 制限: 600 リクエスト/分
  • 認証: Bearerキー

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

POST/api/v1/workflows/{workflow_id}
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')

概要

概要

エンドポイント
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')

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"
}

リクエストパラメータ

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:9
resolution

型: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

値: 2K4K

エラー

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_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. ステップ 1

    API キーを生成

    Workflows は、他のすべての Photta 機能と同じ認証情報と同じ credits 残高を使用します。

  2. ステップ 2

    ワークフローカタログを一覧取得

    GET `/api/v1/workflows` は、7 つのカテゴリにわたる 53 種類のテンプレートを返します。各テンプレートは独自の画像スロット、オプションの enum、デフォルトのアスペクト比を定義しています。`category` で絞り込みが可能です — 未知のカテゴリは無視されず 400 を返します。

  3. ステップ 3

    実行リクエストを POST

    カタログエントリから取得した `images`(スロット ID から画像へのマップ)と `options`(オプション ID から選択肢 ID へのマップ)を指定して POST `/api/v1/workflows/:workflow_id` を実行します。`user_text` は自由形式のスタイリングリクエストを受け付け、`num_images` は 1 回の呼び出しで 1 から 4 枚の画像を処理します。

  4. ステップ 4

    すべてのアイテムをポーリング

    202 レスポンスには、リクエストされた画像ごとに 1 つのアイテムが含まれます。各 ID に対して、`data.status` が `completed` または `failed` になるまで 3 秒ごとに GET `/api/v1/workflows/generations/:id` を実行します。通常の完了時間は画像 1 枚あたり 20 から 60 秒です。

  5. ステップ 5

    ダウンロードして永続化

    完了した各アイテムには独自の `output_url` が含まれます。アイテムは個別に完了するため、残りがレンダリング中であっても最初のアイテムを公開できます。

ワークフロー実行前にエンジニアからよくある質問

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` でフィルタリングされたページネーション表示を取得できます。

関連機能

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

5分でAPIを試す

Photta APIキーを生成し、上記のcURLスニペットを貼り付ければ、コーヒーが淹れ終わる前に最初のモデル着用画像が手に入ります。

  • 20–60 sec / image
  • 2Kで4 credits · 4Kで5 credits
  • 非同期、ポーリング
  • 600 リクエスト/分
  • Bearerキー