Capacidad · Workflows

Workflows API una llamada, un preset

En una frase

La API de workflows de Photta ejecuta plantillas de escenas listas para usar sobre las imágenes de tus productos. Obtén el catálogo con fetch, completa los slots de imagen y las opciones del workflow, haz POST y luego realiza polling sobre cada elemento devuelto hasta que finalice.

  • Tiempo típico: 20–60 sec / image
  • Credits: 4 credits a 2K · 5 credits a 4K
  • Procesamiento: asíncrono, polling
  • Límites: 600 requests/min
  • Autenticación: Bearer key

Cada cifra de esta página proviene de la documentación de la API de 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')

De un vistazo

De un vistazo

Endpoint
POST /api/v1/workflows/{workflow_id}
Autenticación
Bearer API key
Procesamiento
Asíncrono — realiza polling al endpoint de estado
Tiempo típico
20–60 sec / image
Credits
4 credits a 2K · 5 credits a 4K
Relaciones de aspecto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Límites de entrada
Hasta 10 MB por imagen; JPEG, PNG, WebP
Idempotente
No

Petición y respuesta

Petición

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 / Completado

{
  "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 de la petición

workflow_id

Tipo: stringObligatorio

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

images

Tipo: objectObligatorio

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

Errores

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.

Límites

  • 600 solicitudes por minuto por API key (Ventana fija; el límite es el mismo en todos los planes)
  • Un 429 incluye Retry-After: 30 segundos
  • Hasta 10 MB por imagen
  • Formatos: JPEG, PNG, WebP
  • Lotes simultáneos por plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — la API no envía webhooks.

Obtén el catálogo con fetch, completa los slots, ejecuta

Lista los workflows, completa sus slots declarados, envía, realiza polling de cada elemento, descarga.

  1. Paso 1

    Genera una API key

    Los workflows utilizan las mismas credenciales y el mismo balance de credits que cualquier otra capacidad de Photta.

  2. Paso 2

    Listar el catálogo de workflows

    GET `/api/v1/workflows` devuelve las 53 plantillas distribuidas en 7 categorías, cada una declarando sus propios slots de imagen, enums de opciones y relación de aspecto predeterminada. Filtra con `category`; una categoría desconocida devuelve 400 en lugar de ser ignorada.

  3. Paso 3

    Haz POST de la ejecución

    POST `/api/v1/workflows/:workflow_id` con `images` (slot id a imágenes) y `options` (option id a choice id), ambos obtenidos de la entrada del catálogo. `user_text` acepta una solicitud de estilo en texto libre, y `num_images` procesa de 1 a 4 imágenes en una sola llamada.

  4. Paso 4

    Realiza polling de cada elemento

    La respuesta 202 incluye un elemento por cada imagen solicitada. Haz GET a `/api/v1/workflows/generations/:id` cada 3 segundos para cada id hasta que `data.status` sea `completed` o `failed`; el tiempo típico de finalización es de 20 a 60 segundos por imagen.

  5. Paso 5

    Descarga y persiste

    Cada elemento completado incluye su propia `output_url`. Los elementos terminan de forma independiente, por lo que puedes publicar el primero mientras el resto aún se está renderizando.

Preguntas que los desarrolladores hacen antes de ejecutar workflows

¿Qué es la API de workflows?

Un catálogo de plantillas de escenas listas para usar que ejecutas sobre las fotografías de tus propios productos. En lugar de armar un prompt, eliges un workflow y completas los slots de imagen y las opciones que este declara.

¿Cuánto cuesta la ejecución de un workflow?

4 credits por imagen en 2K y 5 por imagen en 4K, multiplicado por `num_images`. El catálogo contiene el precio en tiempo real de cada workflow; léelo desde allí en lugar de asumir un valor.

¿Cómo encuentro el id de un workflow?

GET `/api/v1/workflows`. Cada entrada contiene su id, su categoría, sus slots de imagen y sus opciones. Filtra la lista con `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` o `watch`.

¿Qué se envía en images y options?

`images` mapea un slot id de la entrada del catálogo a un array de imágenes, ya sea como URLs https o URIs de datos base64. `options` mapea un option id a uno de los choice ids de esa opción. Ambas estructuras provienen del catálogo, motivo por el cual la integración no se rompe con nuevos workflows.

¿Cuántas imágenes puede producir una ejecución?

`num_images` acepta de 1 a 4. Cada imagen se genera de forma independiente y recibe su propio item id en la respuesta, por lo que una puede fallar sin comprometer a las demás.

¿Cómo hago polling para obtener los resultados?

Haz polling de cada elemento por separado: GET `/api/v1/workflows/generations/:id` cada 3 segundos. GET `/api/v1/workflows/generations/list` ofrece una vista paginada filtrada por `workflow_id` o `status`.

Capacidades relacionadas

Cada cifra de esta página proviene de la documentación de la API de Photta · verificado

Prueba la API en cinco minutos

Genera una API key de Photta, pega el snippet de cURL de arriba y tendrás tu primera imagen con modelo antes de que termine de prepararse el café.

  • 20–60 sec / image
  • 4 credits a 2K · 5 credits a 4K
  • asíncrono, polling
  • 600 requests/min
  • Bearer key