Capacidade · Workflows
API de Workflows uma chamada, um preset
Em uma frase
A API de workflows da Photta executa templates de cena prontos nas imagens dos seus produtos. Obtenha o catálogo, preencha os slots de imagem e as opções do workflow, faça o POST e realize o polling de cada item retornado até a conclusão.
- Tempo típico: 20–60 sec / image
- Credits: 4 credits em 2K · 5 credits em 4K
- Processamento: assíncrono, polling
- Limites: 600 requisições/min
- Autenticação: Chave Bearer
Todos os números nesta página vêm de a documentação da API da Photta · verificado
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"]Visão geral
Visão geral
- Endpoint
- POST /api/v1/workflows/{workflow_id}
- Autenticação
- API key Bearer
- Processamento
- Assíncrono — faça polling no endpoint de status
- Tempo típico
- 20–60 sec / image
- Credits
- 4 credits em 2K · 5 credits em 4K
- Proporções de tela
- 3:4 · 1:1 · 4:3 · 9:16 · 16:9
- Limites de entrada
- Até 10 MB por imagem; JPEG, PNG, WebP
- Idempotente
- Não
Requisição e resposta
Requisição
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 / Concluído
{
"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"
}Parâmetros da requisição
workflow_idTipo: stringObrigatório
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTipo: objectObrigatório
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.
optionsTipo: 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_textTipo: 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_imagesTipo: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioTipo: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
Valores:3:41:14:39:1616:9resolutionTipo: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Valores:2K4K
Erros
- 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.
Limites
- 600 requisições por minuto por API key (Janela fixa; o limite é o mesmo em todos os planos)
- Um 429 retorna Retry-After: 30 segundos
- Até 10 MB por imagem
- Formatos: JPEG, PNG, WebP
- Batches concorrentes por plano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
- Apenas polling — a API não envia webhooks.
Obtenha o catálogo, preencha os slots, execute
Liste os workflows, preencha os slots declarados, envie, faça o polling de cada item e baixe.
Passo 1
Gerar uma chave de API
Os workflows usam as mesmas credenciais e o mesmo saldo de credits que qualquer outra capacidade da Photta.
Passo 2
Listar o catálogo de workflows
GET `/api/v1/workflows` retorna os 53 templates distribuídos em 7 categorias, cada um declarando seus próprios slots de imagem, enums de opções e proporção de tela padrão. Filtre com `category` — uma categoria desconhecida retorna 400 em vez de ser ignorada.
Passo 3
Fazer o POST da execução
POST `/api/v1/workflows/:workflow_id` com `images` (id do slot para imagens) e `options` (id da opção para id da escolha), ambos obtidos da entrada do catálogo. `user_text` aceita uma solicitação de estilo em texto livre, e `num_images` executa de 1 a 4 imagens em uma única chamada.
Passo 4
Fazer polling de cada item
A resposta 202 traz um item por imagem solicitada. GET `/api/v1/workflows/generations/:id` a cada 3 segundos para cada id até que `data.status` seja `completed` ou `failed`; o tempo típico de conclusão é de 20 a 60 segundos por imagem.
Passo 5
Baixar e persistir
Cada item concluído traz seu próprio `output_url`. Os itens terminam de forma independente, permitindo publicar o primeiro enquanto os demais ainda estão sendo renderizados.
O mesmo endpoint em Node.js, Python e cURL
Node.js
API de Workflows em Node.js
Chame aPI de Workflows da Photta a partir de um backend em Node.js com fetch nativo. Nenhum SDK é necessário: armazene sua chave, envie o job e faça polling pelo resultado.
LerPython
API de Workflows em Python
Chame aPI de Workflows do Photta em Python com a biblioteca requests. Wrapper de trinta linhas, compatível com async via httpx, funciona em Django, FastAPI e Celery.
LercURL
API de Workflows com cURL
Chame a aPI de Workflows da Photta diretamente do shell com cURL. Envie, faça polling, baixe — todos os snippets funcionam com o jq para pipelines em script.
Ler
Perguntas que desenvolvedores fazem antes de executar workflows
O que é a API de workflows?
Um catálogo de templates de cena prontos que você executa nas fotografias dos seus próprios produtos. Em vez de montar um prompt, você escolhe um workflow e preenche os slots de imagem e as opções que ele declara.
Quanto custa a execução de um workflow?
4 credits por imagem em 2K e 5 por imagem em 4K, multiplicados por `num_images`. O catálogo traz o preço em tempo real de cada workflow — leia esse valor diretamente de lá em vez de assumi-lo.
Como encontro o id de um workflow?
GET `/api/v1/workflows`. Cada entrada traz seu id, sua categoria, seus slots de imagem e suas opções. Filtre a lista com `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` ou `watch`.
O que vai em images e options?
`images` mapeia um id de slot da entrada do catálogo para um array de imagens, como URLs https ou data URIs em base64. `options` mapeia um id de opção para um dos ids de escolha dessa opção. Ambas as estruturas vêm do catálogo, e é por isso que a integração continua funcionando com novos workflows.
Quantas imagens uma única execução pode gerar?
`num_images` aceita de 1 a 4. Cada imagem é gerada de forma independente e recebe seu próprio id de item na resposta, portanto uma pode falhar sem comprometer as outras.
Como faço polling pelos resultados?
Faça o polling de cada item separadamente: GET `/api/v1/workflows/generations/:id` a cada 3 segundos. GET `/api/v1/workflows/generations/list` retorna uma visualização paginada filtrada por `workflow_id` ou `status`.
Capacidades relacionadas
Recursos
API de try-on virtual para roupas
API REST que veste roupas em manequins de IA. Assíncrona, geração em 1.5–4 minutos, 5 credits em 2K, 6 em 4K. Exemplos em cURL, Node.js e Python.
Ver o endpointRecursos
API de try-on de joias para colares, anéis, pulseiras e brincos
Insira colares, anéis, pulseiras e brincos em modelos de IA via REST. 5 credits em 2K, manequins em close-up integrados, renderização sensível a reflexos direto da documentação da Photta.
Ver o endpointConstruir
Crie um serviço de fotografia de produtos com IA
O playbook de um fundador para revender a API de virtual try-on da Photta como um SaaS white-label: chaves por tenant, fanout em lote, faturamento por credit, realidade de SLA.
Ver o endpointComparar
Photta vs Ayna — API para desenvolvedores ou estúdio focado em Shopify
Photta vs Ayna comparados: três endpoints REST vs um estúdio focado em Shopify + API. Ambos têm pontos fortes. Obtido de cada site em 2026-04-19.
Ver o endpointInício rápido
Primeira imagem no Photta em menos de cinco minutos.
Cadastre-se, gere uma chave de API, execute sua primeira chamada cURL, faça polling até a conclusão, persista o resultado. Cinco etapas, documentadas de ponta a ponta.
Ver o endpointReferência
Erros da Photta API
A lista completa de tipos de erro da Photta API com seus status codes, o formato do corpo de erro e quais falhas valem a pena tentar novamente.
Ver o endpointReferência
Rate limits da API Photta
O rate limit da API Photta, sua janela, o header Retry-After, o intervalo de polling e os limites de simultaneidade por plano, tudo extraído da documentação da API.
Ver o endpoint
Todos os números nesta página vêm de a documentação da API da Photta · verificado
Experimente a API em cinco minutos
Gere uma chave de API do Photta, cole o snippet de cURL acima e você terá sua primeira imagem com modelo antes que o café termine de passar.
- 20–60 sec / image
- 4 credits em 2K · 5 credits em 4K
- assíncrono, polling
- 600 requisições/min
- Chave Bearer