Inicio rápido

Tu primera imagen de Photta en menos de cinco minutos.

En una frase

Regístrate en ai.photta.app, haz clic en Generate API key, expórtala como PHOTTA_API_KEY, haz un POST a /api/v1/tryon/apparel y haz polling del ID de generación devuelto cada 3 segundos hasta que el estado cambie a completed — normalmente entre 1.5 y 4 minutos.

Obtener una API keyLeer la documentación
  • Autenticación: Bearer key
  • Procesamiento: asíncrono, polling
  • Límites: 600 requests/min

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/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Cómo funciona

Cinco comandos desde cero hasta la primera imagen

Pégalos en una terminal en orden. Cada fragmento es autónomo y solo utiliza curl + jq.

  1. Paso 1

    Generar una API key

    Regístrate en ai.photta.app y abre el panel de Developers. Haz clic en Generate API key — las claves activas comienzan con photta_live_. Expórtala para que el resto de la guía pueda leerla desde tu shell.

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. Paso 2

    Haz el POST de tu primer try-on

    Llama a /api/v1/tryon/apparel con una URL de imagen de producto y un mannequin_id. La API responde 202 Accepted de inmediato y devuelve un ID de generación en data.id.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

  3. Paso 3

    Haz polling hasta que se complete

    Haz GET a /api/v1/tryon/apparel/:id cada 3 segundos. El tiempo típico de finalización es de 1.5–4 minutos. Establece un límite superior de intentos para que un trabajo atascado no bloquee tu script indefinidamente.

    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

  4. Paso 4

    Persiste la salida

    Cuando status cambie a completed, data.output_url contendrá la imagen renderizada. Descarga los bytes en tu propio almacenamiento para que tu producto no dependa del CDN de Photta para el renderizado.

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. Paso 5

    Gestiona los modos de fallo adecuadamente

    Bifurca según el código de estado HTTP: 402 para créditos insuficientes, 429 para límites de tasa (respeta Retry-After), 5xx para errores transitorios del servidor. Cada cuerpo de error incluye un error.code legible por máquina sobre el que puedes actuar.

    case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

Preguntas frecuentes de desarrolladores

Preguntas sobre cómo empezar

¿Cuánto tiempo lleva la guía de inicio rápido?

Cinco minutos para el registro + generación de la clave + primer cURL. La generación en sí tarda de 1.5 a 4 minutos, así que calcula diez minutos de reloj antes de ver tu primera imagen con modelo.

¿Necesito una tarjeta de crédito para probarlo?

Las cuentas nuevas incluyen créditos de prueba que puedes usar antes de pagar. Cuando estés listo para pasar a producción, suscríbete a un plan para obtener un balance mensual de créditos más alto y límites de tasa más rápidos.

¿Qué endpoint debería probar primero?

Try-on de ropa (/api/v1/tryon/apparel): es el más utilizado, la documentación es la más completa y cubre el patrón asíncrono + polling que reutilizan todos los demás endpoints de Photta. Una vez que te sientas cómodo allí, joyería y maniquí invisible funcionan de la misma manera.

¿Puedo ejecutarlo desde el navegador?

No. Tu clave de API debe permanecer en el lado del servidor; enviarla a un navegador la expone a todos los visitantes. Enruta las llamadas a través de un proxy ligero en tu propio backend (route handler de Next.js, Express, Flask, Lambda) y haz que el navegador se comunique con tu proxy en su lugar.

Páginas relacionadas

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

Estás a cinco minutos de tu primera imagen

Obtener una API keyExplora la API
  • Bearer key
  • asíncrono, polling
  • 600 requests/min