Yetenek · Workflows

Workflows API tek çağrı, tek preset

Tek cümlede

Photta'nın workflows API'si, ürün görselleriniz üzerinde hazır sahne şablonlarını çalıştırır. Kataloğu fetch edin, workflow'un görsel slotlarını ve seçeneklerini doldurun, POST edin, ardından dönen her bir öğeyi tamamlanana kadar poll edin.

  • Tipik süre: 20–60 sec / image
  • Credits: 2K'da 4 credits · 4K'da 5 credits
  • İşleme: asenkron, polling
  • Sınırlar: 600 istek/dk
  • Kimlik doğrulama: Bearer anahtarı

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

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

Genel bakış

Genel bakış

Endpoint
POST /api/v1/workflows/{workflow_id}
Kimlik doğrulama
Bearer API anahtarı
İşleme
Asenkron — durum endpoint'ini sorgulayın (poll)
Tipik süre
20–60 sec / image
Credits
2K'da 4 credits · 4K'da 5 credits
En-boy oranları
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Girdi sınırları
Görsel başına en fazla 10 MB; JPEG, PNG, WebP
Idempotent
Hayır

İstek ve yanıt

İstek

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

İstek parametreleri

workflow_id

Tür: stringZorunlu

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

images

Tür: objectZorunlu

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

Tür: 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

Tür: 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

Tür: integer

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

= 1

aspect_ratio

Tür: string

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

= 3:4

Değerler: 3:41:14:39:1616:9
resolution

Tür: string

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

= 2K

Değerler: 2K4K

Hatalar

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.

Sınırlar

  • API anahtarı başına dakikada 600 istek (Sabit pencere; limit her planda aynıdır)
  • 429 yanıtı Retry-After: 30 saniye içerir
  • Görsel başına en fazla 10 MB
  • Formatlar: JPEG, PNG, WebP
  • Plan başına eşzamanlı toplu işlem: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Yalnızca polling — API webhook göndermez.

Kataloğu fetch edin, slotları doldurun, çalıştırın

Workflow'ları listeleyin, tanımlanan slotlarını doldurun, gönderin, her öğeyi poll edin, indirin.

  1. Adım 1

    Bir API anahtarı oluşturun

    Workflow'lar, diğer tüm Photta yetenekleriyle aynı kimlik bilgilerini ve aynı kredi bakiyesini kullanır.

  2. Adım 2

    Workflow kataloğunu listeleyin

    GET `/api/v1/workflows`, her biri kendi görsel slotlarını, seçenek enum'larını ve varsayılan en-boy oranını tanımlayan 7 kategorideki 53 şablonu döndürür. `category` ile filtreleyin — bilinmeyen bir kategori yok sayılmak yerine 400 döndürür.

  3. Adım 3

    Çalıştırma isteğini POST edin

    Her ikisi de katalog girdisinden alınan `images` (slot id'den görsellere) ve `options` (seçenek id'den tercih id'sine) ile POST `/api/v1/workflows/:workflow_id` çağrısı yapın. `user_text` serbest metin stil talebini kabul eder ve `num_images` tek bir çağrıda 1 ila 4 görsel çalıştırır.

  4. Adım 4

    Her öğeyi poll edin

    202 yanıtı, talep edilen görsel başına bir öğe taşır. Her id için `data.status` değeri `completed` veya `failed` olana kadar her 3 saniyede bir GET `/api/v1/workflows/generations/:id` çağrısı yapın; tipik tamamlanma süresi görsel başına 20 ila 60 saniyedir.

  5. Adım 5

    İndirin ve kalıcı hale getirin

    Tamamlanan her öğe kendi `output_url` değerini taşır. Öğeler bağımsız olarak biter; böylece diğerleri render edilirken ilkini yayınlayabilirsiniz.

Geliştiricilerin workflow'ları çalıştırmadan önce sorduğu sorular

Workflows API nedir?

Kendi ürün fotoğraflarınız üzerinde çalıştırdığınız hazır sahne şablonlarından oluşan bir katalog. Bir prompt hazırlamak yerine, bir workflow seçer ve tanımladığı görsel slotlarını ve seçeneklerini doldurursunuz.

Bir workflow çalıştırması ne kadara mal olur?

2K'da görsel başına 4 credits ve 4K'da görsel başına 5 credits, `num_images` ile çarpılır. Katalog, her workflow için canlı fiyatı taşır — tahmin etmek yerine oradan okuyun.

Bir workflow id'sini nasıl bulurum?

GET `/api/v1/workflows`. Her girdi kendi id'sini, kategorisini, görsel slotlarını ve seçeneklerini taşır. Listeyi `category` ile filtreleyin: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` veya `watch`.

images ve options içine ne yazılır?

`images`, katalog girdisindeki bir slot id'sini https URL'leri veya base64 veri URI'leri olarak bir görsel dizisine eşler. `options`, bir seçenek id'sini o seçeneğin tercih id'lerinden birine eşler. Her iki yapı da katalogdan gelir; entegrasyonun yeni workflow'lar eklendiğinde bozulmama nedeni budur.

Bir çalıştırma kaç görsel üretebilir?

`num_images` 1 ila 4 kabul eder. Her görsel bağımsız olarak üretilir ve yanıtta kendi öğe id'sini alır; bu sayede biri başarısız olduğunda diğerleri etkilenmez.

Sonuçlar için nasıl polling yaparım?

Her öğeyi ayrı ayrı sorgulayın: her 3 saniyede bir GET `/api/v1/workflows/generations/:id`. GET `/api/v1/workflows/generations/list` ise `workflow_id` veya `status` ile filtrelenmiş sayfalanmış bir görünüm sunar.

İlgili yetenekler

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

API'yi beş dakikada deneyin

Bir Photta API key oluşturun, yukarıdaki cURL kod parçacığını yapıştırın; kahveniz demlenmeden önce model üzerindeki ilk görselinizi alın.

  • 20–60 sec / image
  • 2K'da 4 credits · 4K'da 5 credits
  • asenkron, polling
  • 600 istek/dk
  • Bearer anahtarı