Kapabilitas · Workflows

Workflows API satu panggilan, satu preset

Ringkasan singkat

Workflows API Photta menjalankan templat scene siap pakai menggunakan gambar produk Anda. Ambil katalog, isi slot gambar dan opsi workflow, POST, lalu lakukan polling untuk setiap item yang dikembalikan hingga selesai.

  • Waktu umum: 20–60 sec / image
  • Credits: 4 credits pada 2K · 5 credits pada 4K
  • Pemrosesan: async, polling
  • Batasan: 600 requests/min
  • Autentikasi: Bearer key

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa

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')

Sekilas

Sekilas

Endpoint
POST /api/v1/workflows/{workflow_id}
Autentikasi
API key Bearer
Pemrosesan
Asinkron — lakukan polling ke endpoint status
Waktu umum
20–60 sec / image
Credits
4 credits pada 2K · 5 credits pada 4K
Rasio aspek
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Batas input
Hingga 10 MB per gambar; JPEG, PNG, WebP
Idempoten
Tidak

Request dan response

Request

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

Parameter request

workflow_id

Tipe: stringWajib

The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.

images

Tipe: objectWajib

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

Tipe: 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

Tipe: 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

Tipe: integer

Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.

= 1

aspect_ratio

Tipe: string

Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).

= 3:4

Nilai: 3:41:14:39:1616:9
resolution

Tipe: string

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

= 2K

Nilai: 2K4K

Error

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.

Batasan

  • 600 request per menit per API key (Fixed window; batasannya sama di setiap paket)
  • Respons 429 menyertakan Retry-After: 30 detik
  • Hingga 10 MB per gambar
  • Format: JPEG, PNG, WebP
  • Batch konkuren per paket: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Hanya polling — API tidak mengirim webhook.

Ambil katalog, isi slot, jalankan

Daftar workflow, isi slot yang dideklarasikan, kirim, polling setiap item, unduh.

  1. Langkah 1

    Buat API key

    Workflow menggunakan kredensial dan saldo credits yang sama seperti setiap kapabilitas Photta lainnya.

  2. Langkah 2

    Daftar katalog workflow

    GET `/api/v1/workflows` mengembalikan 53 templat di 7 kategori, masing-masing mendeklarasikan slot gambarnya sendiri, enum opsi, dan rasio aspek default. Filter menggunakan `category` — kategori yang tidak dikenal akan mengembalikan 400 alih-alih diabaikan.

  3. Langkah 3

    POST eksekusinya

    POST `/api/v1/workflows/:workflow_id` dengan `images` (id slot ke gambar) dan `options` (id opsi ke id pilihan), keduanya diambil dari entri katalog. `user_text` menerima permintaan gaya berupa teks bebas, dan `num_images` menjalankan 1 hingga 4 gambar dalam satu panggilan.

  4. Langkah 4

    Polling setiap item

    Respons 202 memuat satu item per gambar yang diminta. GET `/api/v1/workflows/generations/:id` setiap 3 detik untuk setiap id hingga `data.status` bernilai `completed` atau `failed`; waktu penyelesaian tipikal adalah 20 hingga 60 detik per gambar.

  5. Langkah 5

    Unduh dan simpan permanen

    Setiap item yang selesai membawa `output_url`-nya sendiri. Item selesai secara independen, jadi Anda dapat memublikasikan item pertama selagi sisanya masih dirender.

Pertanyaan yang diajukan developer sebelum menjalankan workflow

Apa itu workflows API?

Katalog templat scene siap pakai yang Anda jalankan menggunakan foto produk Anda sendiri. Alih-alih menyusun prompt, Anda memilih workflow dan mengisi slot gambar serta opsi yang dideklarasikannya.

Berapa biaya eksekusi satu workflow?

4 credits per gambar pada 2K dan 5 per gambar pada 4K, dikalikan dengan `num_images`. Katalog memuat harga langsung untuk setiap workflow — baca dari sana daripada berasumsi.

Bagaimana cara menemukan id workflow?

GET `/api/v1/workflows`. Setiap entri memuat id, kategori, slot gambar, dan opsinya. Filter daftarnya dengan `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag`, atau `watch`.

Apa yang harus diisi di images dan options?

`images` memetakan id slot dari entri katalog ke sebuah array gambar, berupa URL https atau data URI base64. `options` memetakan id opsi ke salah satu id pilihan opsi tersebut. Kedua struktur ini berasal dari katalog, itulah mengapa integrasi tetap berjalan mulus meskipun ada workflow baru.

Berapa banyak gambar yang dapat dihasilkan dalam satu eksekusi?

`num_images` menerima 1 hingga 4. Setiap gambar di-generate secara independen dan mendapatkan id itemnya sendiri dalam respons, sehingga jika satu gagal tidak akan menggagalkan yang lain.

Bagaimana cara melakukan polling untuk hasilnya?

Lakukan polling pada setiap item secara terpisah: GET `/api/v1/workflows/generations/:id` setiap 3 detik. GET `/api/v1/workflows/generations/list` menampilkan tampilan terhalaman yang difilter berdasarkan `workflow_id` atau `status`.

Kapabilitas terkait

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa

Coba API dalam lima menit

Buat Photta API key, tempel cuplikan cURL di atas, dan Anda akan mendapatkan gambar on-model pertama sebelum kopi selesai diseduh.

  • 20–60 sec / image
  • 4 credits pada 2K · 5 credits pada 4K
  • async, polling
  • 600 requests/min
  • Bearer key