Capacidad · Fotos de detalle

API de fotos de detalle de producto para primeros planos

En una frase

La API de fotos de detalle de Photta genera un primer plano de un área específica de un producto. Una llamada gratuita de análisis sugiere detalles que vale la pena fotografiar; la llamada de generación cuesta 3 credits fijos, sin niveles de resolución.

Obtener una API key Leer la documentación

Tiempo típico: 20–60 sec
Credits: 3 credits
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 2026-09-10

POST/api/v1/detail-photos

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
    "detail_label": "collar stitching",
    "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
    "framing": "extreme-closeup",
    "source_type": "apparel"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/detail-photos",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
      "detail_label": "collar stitching",
      "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
      "framing": "extreme-closeup",
      "source_type": "apparel"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

De un vistazo

Endpoint: POST /api/v1/detail-photos
Autenticación: Bearer API key
Procesamiento: Asíncrono — realiza polling al endpoint de estado
Tiempo típico: 20–60 sec
Credits: 3 credits
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/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/detail-photos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
    "detail_label": "collar stitching",
    "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
    "framing": "extreme-closeup",
    "source_type": "apparel"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/detail-photos",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
      "detail_label": "collar stitching",
      "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
      "framing": "extreme-closeup",
      "source_type": "apparel"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / Completado

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "completed",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "output_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10-thumb.jpg",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z",
    "completed_at": "2026-07-30T14:20:42Z",
    "duration_ms": 42000
  },
  "request_id": "req_dtl003"
}

Parámetros de la petición

CampoDescripción

product_image

Tipo: stringObligatorio

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

Tipo: stringObligatorio

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

Tipo: string

Extra guidance for the close-up. Max 400 characters.

framing

Tipo: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

extreme-closeupcloseupmedium-closeup

source_type

Tipo: string

Tunes what is preserved in the close-up.

= apparel

appareljewelry

Errores

EstadoTipoSignificado

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.

Pregunta qué vale la pena fotografiar y luego fotografíalo

Analiza gratis, elige un detalle, envía, haz polling y descarga.

Paso 1
Genera una API key
Las fotos de detalle usan las mismas credenciales y el mismo saldo de credits que cualquier otra capacidad de Photta.
Paso 2
Pregunta qué detalles fotografiar
Haz POST a `/api/v1/detail-photos/analyze` con `product_image`. Devuelve valores sugeridos de `detail_label`, `detail_description` y `framing` para ese producto, de forma sincrónica y sin costo.
Paso 3
Envía el primer plano con POST
Haz POST a `/api/v1/detail-photos` con `product_image` y `detail_label`. Configura `framing` como `extreme-closeup`, `closeup` o `medium-closeup`, `source_type` como `apparel` o `jewelry`, y añade hasta 400 caracteres de `detail_description`.
Paso 4
Haz polling hasta que el trabajo termine
Haz GET a `/api/v1/detail-photos/:id` cada 3 segundos hasta que `data.status` sea `completed` o `failed`; el tiempo típico de finalización es de 20 a 60 segundos.
Paso 5
Descarga y persiste
El cuerpo completado incluye `output_url`. Las fotos de detalle se integran directamente en la galería de la PDP junto a la toma principal.

El mismo endpoint en Node.js, Python y cURL

Preguntas que los desarrolladores hacen antes de implementar fotos de detalle

¿Qué es una API de fotos de detalle?

Un endpoint que genera un primer plano de un área específica de un producto —las costuras del cuello, un broche, el tejido del pecho— a partir de una única fotografía más amplia, sin necesidad de una segunda sesión de estudio con un lente macro.

¿Cuánto cuesta una foto de detalle?

3 credits fijos. No hay niveles de resolución en este endpoint, y la llamada de análisis que sugiere los detalles es gratuita.

¿Qué devuelve el endpoint de análisis?

Una lista de sugerencias, cada una con un `detail_label`, una `detail_description` que explica por qué vale la pena mostrar esa área, y un `framing` recomendado. Pasa cualquier sugerencia directamente a la llamada de generación.

¿Qué tan cerrado es cada encuadre?

`extreme-closeup` llena casi todo el encuadre con el detalle, `closeup` mantiene un poco de contexto a su alrededor y `medium-closeup` muestra el detalle dentro de la prenda o pieza circundante. Elígelo por detalle, no por producto.

¿Puede la fuente ser una imagen generada?

Sí. `product_image` acepta la `output_url` de una generación completada, así como cualquier foto de producto propia, como una URL https o un data URI en base64.

¿Cómo hago polling para obtener el resultado?

GET `/api/v1/detail-photos/:id` cada 3 segundos hasta que `data.status` sea `completed` o `failed`. La llamada de análisis es síncrona y no requiere polling.

Capacidades relacionadas

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

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

Crear una cuenta y obtener una API key Leer la documentación

20–60 sec
3 credits
asíncrono, polling
600 requests/min
Bearer key

API de fotos de detalle de producto para primeros planos

De un vistazo

Petición y respuesta

Parámetros de la petición

Errores

Pregunta qué vale la pena fotografiar y luego fotografíalo

Genera una API key

Pregunta qué detalles fotografiar

Envía el primer plano con POST

Haz polling hasta que el trabajo termine

Descarga y persiste

El mismo endpoint en Node.js, Python y cURL

Preguntas que los desarrolladores hacen antes de implementar fotos de detalle

Capacidades relacionadas

Prueba la API en cinco minutos