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

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

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

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

Parâmetros da requisição

workflow_id

Tipo: stringObrigatório

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

images

Tipo: 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.

options

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

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

Tipo: integer

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

= 1

aspect_ratio

Tipo: 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:9
resolution

Tipo: string

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

= 2K

Valores: 2K4K

Erros

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.

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

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

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