Możliwość · Workflows
Workflows API jedno wywołanie, jeden preset
W jednym zdaniu
API workflows od Photta uruchamia gotowe szablony scen na Twoich zdjęciach produktów. Pobierz katalog, wypełnij sloty na zdjęcia i opcje danego workflow, wyślij POST, a następnie odpytuj o każdy zwrócony element, aż zakończy przetwarzanie.
- Typowy czas: 20–60 sec / image
- Credits: 4 credits w 2K · 5 credits w 4K
- Przetwarzanie: asynchroniczne, polling
- Limity: 600 requests/min
- Uwierzytelnianie: Klucz Bearer
Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono
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"]W skrócie
W skrócie
- Endpoint
- POST /api/v1/workflows/{workflow_id}
- Uwierzytelnianie
- Klucz API Bearer
- Przetwarzanie
- Asynchroniczne — odpytuj endpoint statusu
- Typowy czas
- 20–60 sec / image
- Credits
- 4 credits w 2K · 5 credits w 4K
- Proporcje obrazu
- 3:4 · 1:1 · 4:3 · 9:16 · 16:9
- Limity wejściowe
- Do 10 MB na obraz; JPEG, PNG, WebP
- Idempotentne
- Nie
Żądanie i odpowiedź
Żądanie
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"
}Parametry żądania
workflow_idTyp: stringWymagane
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTyp: objectWymagane
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.
optionsTyp: 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_textTyp: 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_imagesTyp: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioTyp: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
Wartości:3:41:14:39:1616:9resolutionTyp: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Wartości:2K4K
Błędy
- 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.
Limity
- 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
- Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
- Do 10 MB na obraz
- Formaty: JPEG, PNG, WebP
- Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
- Tylko polling — API nie wysyła webhooków.
Pobierz katalog, wypełnij sloty, uruchom
Wylistuj workflows, wypełnij ich zadeklarowane sloty, wyślij żądanie, odpytuj o każdy element, pobierz.
Krok 1
Wygeneruj klucz API
Workflows używają tych samych danych uwierzytelniających i tego samego salda credits, co każda inna możliwość Photta.
Krok 2
Pobierz listę z katalogu workflow
GET `/api/v1/workflows` zwraca 53 szablony z 7 kategorii, z których każdy deklaruje własne sloty na zdjęcia, enumy opcji i domyślny współczynnik proporcji. Filtruj za pomocą `category` — nieznana kategoria zwraca 400, zamiast zostać zignorowana.
Krok 3
Wyślij żądanie uruchomienia (POST)
Wyślij POST `/api/v1/workflows/:workflow_id` z `images` (mapowanie slot id na zdjęcia) oraz `options` (mapowanie option id na choice id), pobranymi z wpisu w katalogu. `user_text` przyjmuje dowolny tekst żądania stylizacji, a `num_images` pozwala wygenerować od 1 do 4 zdjęć w jednym wywołaniu.
Krok 4
Odpytuj o każdy element
Odpowiedź 202 zawiera jeden element na każde żądane zdjęcie. Wykonuj GET `/api/v1/workflows/generations/:id` co 3 sekundy dla każdego id, dopóki `data.status` nie przyjmie wartości `completed` lub `failed`; typowy czas ukończenia wynosi od 20 do 60 sekund na zdjęcie.
Krok 5
Pobierz i zapisz
Każdy ukończony element zawiera własny `output_url`. Elementy kończą przetwarzanie niezależnie, więc możesz opublikować pierwszy, podczas gdy reszta wciąż się renderuje.
Ten sam endpoint w Node.js, Python i cURL
Node.js
Workflows API w Node.js
Wywołaj workflows API od Photta z backendu Node.js za pomocą natywnego fetch. SDK nie jest wymagane: zapisz klucz, wyślij zadanie, odpytuj o wynik.
CzytajPython
Workflows API w Pythonie
Wywołuj Photta workflows API w Pythonie za pomocą biblioteki requests. Trzydziestowierszowy wrapper, przyjazny dla async dzięki httpx, działa w Django, FastAPI i Celery.
CzytajcURL
Workflows API z cURL
Wywołuj workflows API Photta bezpośrednio z powłoki za pomocą cURL. Wysyłaj, odpytuj, pobieraj — każdy fragment kodu współpracuje z jq w zautomatyzowanych potokach.
Czytaj
Pytania zadawane przez programistów przed uruchomieniem workflows
Czym jest workflows API?
To katalog gotowych szablonów scen, które uruchamiasz na własnych fotografiach produktów. Zamiast budować prompt, wybierasz workflow i wypełniasz sloty na zdjęcia oraz zadeklarowane opcje.
Ile kosztuje uruchomienie workflow?
4 credits za zdjęcie w 2K i 5 za zdjęcie w 4K, pomnożone przez `num_images`. Katalog zawiera aktualną cenę dla każdego workflow — odczytuj ją stamtąd, zamiast zakładać wartości z góry.
Jak znaleźć workflow id?
GET `/api/v1/workflows`. Każdy wpis zawiera swój id, kategorię, sloty na zdjęcia oraz opcje. Filtruj listę za pomocą parametru `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` lub `watch`.
Co powinno znaleźć się w images i options?
`images` mapuje slot id z wpisu w katalogu na tablicę zdjęć jako adresy https URL lub URI danych base64. `options` mapuje option id na jedno z pól choice id danej opcji. Obie struktury pochodzą z katalogu, dzięki czemu integracja pozostaje aktualna przy dodawaniu nowych workflows.
Ile zdjęć można wygenerować w ramach jednego uruchomienia?
`num_images` przyjmuje wartości od 1 do 4. Każde zdjęcie jest generowane niezależnie i otrzymuje własny item id w odpowiedzi, więc błąd jednego nie wpływa na pozostałe.
Jak odpytywać o wyniki?
Odpytuj każdy element osobno: GET `/api/v1/workflows/generations/:id` co 3 sekundy. GET `/api/v1/workflows/generations/list` zwraca widok stronicowany, filtrowany według `workflow_id` lub `status`.
Powiązane możliwości
Możliwości
API wirtualnego try-on dla odzieży
REST API, które nakłada odzież na manekiny AI. Asynchroniczne, generowanie w 1.5–4 minuty, 5 credits przy 2K, 6 przy 4K. Przykłady dla cURL, Node.js i Python.
Zobacz endpointMożliwości
API try-on biżuterii dla naszyjników, pierścionków, bransoletek i kolczyków
Nakładaj naszyjniki, pierścionki, bransoletki i kolczyki na modele AI przez REST. 5 credits w 2K, wbudowane manekiny w zbliżeniu, renderowanie uwzględniające refleksy światła prosto z dokumentacji Photta.
Zobacz endpointTwórz
Zbuduj usługę fotografii produktowej AI
Playbook dla founderów dotyczący odsprzedaży API virtual try-on od Photta jako SaaS white-label: klucze tenantów, batch fanout, rozliczenia per-credit, realia SLA.
Zobacz endpointPorównaj
Photta vs Ayna — API dla deweloperów czy studio skupione na Shopify
Porównanie Photta vs Ayna: trzy endpointy REST vs studio zorientowane na Shopify + API. Obydwa mają mocne strony. Źródło: strony dostawców z dnia 2026-04-19.
Zobacz endpointSzybki start
Pierwszy obraz z Photta w mniej niż pięć minut.
Zarejestruj się, wygeneruj klucz API, wykonaj pierwsze wywołanie cURL, odpytuj aż do ukończenia, zapisz wynik. Pięć kroków opisanych od początku do końca.
Zobacz endpointDokumentacja
Błędy Photta API
Pełna lista typów błędów Photta API wraz z ich kodami statusu, strukturą treści błędu oraz informacją, które niepowodzenia warto ponowić.
Zobacz endpointDokumentacja
Rate limity Photta API
Rate limit Photta API, jego okno, nagłówek Retry-After, interwał dla pollingu oraz limity współbieżności według planu — wszystko prosto z dokumentacji API.
Zobacz endpoint
Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono
Wypróbuj API w 5 minut
Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.
- 20–60 sec / image
- 4 credits w 2K · 5 credits w 4K
- asynchroniczne, polling
- 600 requests/min
- Klucz Bearer