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
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"]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')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"
}Parameter request
workflow_idTipe: stringWajib
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTipe: 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.
optionsTipe: 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_textTipe: 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_imagesTipe: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioTipe: 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:9resolutionTipe: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Nilai:2K4K
Error
- 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.
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.
Langkah 1
Buat API key
Workflow menggunakan kredensial dan saldo credits yang sama seperti setiap kapabilitas Photta lainnya.
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.
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.
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.
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.
Endpoint yang sama di Node.js, Python, dan cURL
Node.js
Workflows API di Node.js
Panggil workflows API Photta dari backend Node.js dengan fetch native. Tidak memerlukan SDK: simpan kunci Anda, kirim job, lakukan polling untuk hasilnya.
BacaPython
Workflows API di Python
Panggil workflows API Photta di Python dengan library requests. Wrapper tiga puluh baris, ramah asinkron via httpx, bekerja di Django, FastAPI, dan Celery.
BacacURL
Workflows API dengan cURL
Panggil workflows API Photta langsung dari shell menggunakan cURL. Kirim, lakukan polling, unduh — setiap cuplikan kode dapat dipadukan dengan jq untuk pipeline berbasis skrip.
Baca
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
Kapabilitas
Virtual try-on API untuk pakaian
REST API yang memakaikan pakaian pada manekin AI. Asinkron, waktu generasi 1.5–4 menit, 5 credits pada 2K, 6 pada 4K. Contoh cURL, Node.js, dan Python.
Lihat endpointKapabilitas
API try-on perhiasan untuk kalung, cincin, gelang, dan anting
Posisikan kalung, cincin, gelang, dan anting pada model AI via REST. 5 credits pada 2K, manekin close-up bawaan, rendering dengan penanganan refleksi dari dokumentasi Photta.
Lihat endpointBangun
Bangun layanan fotografi produk AI
Playbook founder untuk menjual kembali API virtual try-on Photta sebagai SaaS white-label: kunci tenant, fanout batch, penagihan per-credit, realitas SLA.
Lihat endpointBandingkan
Photta vs Ayna — API developer atau studio berbasis Shopify
Komparasi Photta vs Ayna: tiga REST endpoint vs studio berbasis Shopify + API. Keduanya memiliki keunggulan. Bersumber dari masing-masing situs pada 2026-04-19.
Lihat endpointQuickstart
Gambar Photta pertama dalam waktu kurang dari lima menit.
Daftar, buat API key, jalankan pemanggilan cURL pertama Anda, lakukan polling hingga selesai, simpan hasilnya. Lima langkah, terdokumentasi end-to-end.
Lihat endpointReferensi
Error Photta API
Daftar lengkap tipe error Photta API beserta kode statusnya, format body error, dan kegagalan mana saja yang layak dicoba ulang.
Lihat endpointReferensi
Rate limit Photta API
Rate limit Photta API, window-nya, header Retry-After, interval polling, serta batas konkurensi per paket, seluruhnya dirujuk dari dokumentasi API.
Lihat endpoint
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