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
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"]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')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 / 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"
}{
"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 de la petición
workflow_idTipo: stringObligatorio
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTipo: 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.
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
Errores
- 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.
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.
Paso 1
Genera una API key
Los workflows utilizan las mismas credenciales y el mismo balance de credits que cualquier otra capacidad de Photta.
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.
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.
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.
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.
El mismo endpoint en Node.js, Python y cURL
Node.js
Workflows API en Node.js
Llama a workflows API de Photta desde un backend de Node.js con fetch nativo. Sin SDKs: guarda tu key, envía el trabajo y haz polling para obtener el resultado.
LeerPython
Workflows API en Python
Llama a workflows API de Photta en Python con la biblioteca requests. Wrapper de treinta líneas, compatible con async mediante httpx, funciona en Django, FastAPI y Celery.
LeercURL
Workflows API con cURL
Llama a workflows API de Photta directamente desde la terminal con cURL. Envía, haz polling, descarga: cada fragmento de código se combina con jq para pipelines automatizados.
Leer
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
Capacidades
API de virtual try-on para ropa
API REST que viste maniquíes de IA con prendas. Generación asíncrona de 1.5–4 minutos, 5 créditos en 2K, 6 en 4K. Ejemplos en cURL, Node.js y Python.
Ver el endpointCapacidades
API de try-on de joyas para collares, anillos, pulseras y pendientes
Coloca collares, anillos, pulseras y pendientes en modelos de IA mediante REST. 5 credits en 2K, maniquíes en primer plano integrados y renderizado optimizado para reflejos según la documentación de Photta.
Ver el endpointConstruir
Crea un servicio de fotografía de producto con IA
Un manual para fundadores sobre cómo revender la API de virtual try-on de Photta como un SaaS de marca blanca: claves por tenant, fanout por lotes, facturación por credit y la realidad del SLA.
Ver el endpointComparar
Photta frente a Ayna: API para desarrolladores o estudio centrado en Shopify
Photta vs Ayna frente a frente: tres endpoints REST frente a un estudio enfocado en Shopify + API. Ambos tienen sus ventajas. Datos extraídos de cada sitio el 2026-04-19.
Ver el endpointGuía rápida
Tu primera imagen de Photta en menos de cinco minutos.
Regístrate, genera una API key, ejecuta tu primera llamada cURL, haz polling hasta que se complete y guarda el resultado. Cinco pasos, documentados de principio a fin.
Ver el endpointReferencia
Errores de Photta API
La lista completa de tipos de error de Photta API con sus status codes, la estructura del cuerpo de error y qué fallos merece la pena reintentar.
Ver el endpointReferencia
Rate limits de la API de Photta
El rate limit de la API de Photta, su ventana, la cabecera Retry-After, el intervalo de polling y los límites de concurrencia por plan, todo extraído directamente de la documentación de la API.
Ver el endpoint
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