cURL · API de Try-On Virtual

API de Try-On Virtual con cURL

La forma más rápida de entender cualquier API es llamarla desde la terminal. La documentación de Photta es cURL-first por diseño — todo en esta página se ejecuta en una sola terminal, sin necesidad de Node o Python.

En una frase

Exporta `PHOTTA_API_KEY`, haz un POST a `https://ai.photta.app/api/v1/tryon/apparel` con el cuerpo JSON correcto, captura el ID de generación, luego haz un bucle de `curl … /tryon/apparel/:id` cada 3 segundos hasta que `data.status` cambie a `completed` — típicamente en 1.5 a 4 minutos. Combínalo con `jq` para extraer la URL de salida de la respuesta final.

Actualizado · 2026-04-19

Tu primera solicitud

cURLNode.jsPythoncURL
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "product_type": "dress",
    "product_images": ["https://example.com/dress.jpg"],
    "mannequin_id": "mnq_athena_ts",
    "pose_id": "pose_standing_front",
    "resolution": "2K",
    "aspect_ratio": "3:4"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done

Qué esperar

Typical completion

1.5–4min

2K / 4K credits

5 / 7

Aspect ratios

5

Product types

6

Cómo funciona

API de Try-On Virtual con cURL

Cinco pasos de shell, cero dependencias más allá de curl y jq.

  1. 01

    Paso 1

    Regístrate y genera una clave

    Ve a ai.photta.app, abre la pestaña de Desarrolladores y haz clic en Generar API key. Las claves activas comienzan con `photta_live_`.

  2. 02

    Paso 2

    Exporta la clave

    Pon `export PHOTTA_API_KEY="photta_live_xxx"` en tu perfil de shell o en un archivo `.envrc` para que cada llamada posterior de curl la tome automáticamente.

  3. 03

    Paso 3

    Fija la URL base

    `export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"` mantiene los comandos de curl cortos y facilita el cambio a una URL de sandbox cuando se lance una.

  4. 04

    Paso 4

    Enviar y sondear

    POST a `$PHOTTA_BASE_URL/tryon/apparel` para obtener un ID, luego haz un bucle de `curl $PHOTTA_BASE_URL/tryon/apparel/$ID` cada 3 segundos. Pasa la respuesta a jq para extraer `.data.status` de forma limpia.

  5. 05

    Paso 5

    Persistir el resultado

    Cuando el trabajo se complete, extrae `.data.output_url` con jq y usa `curl -o` para descargar los bytes al almacenamiento local — listo para el siguiente paso de tu pipeline.

Código, de punta a punta

Copy, paste, done.

Four snippets — install prerequisites, wrap the REST call, submit + poll, then handle the errors that actually happen in production.

01cURL is already installed on macOS, Linux, WSL and modern Windows
bash
# Verify curl is available
curl --version

# Export your API key so the rest of the calls can reference it
export PHOTTA_API_KEY="photta_live_xxxxx"
02Set the base URL + auth header once
bash
# Pin the base URL in a shell variable so every call is a one-liner.
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"

# Reusable auth header — every request needs it.
AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
03Submit and poll in one script
bash
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "product_type": "dress",
    "product_images": ["https://example.com/dress.jpg"],
    "mannequin_id": "mnq_athena_ts",
    "pose_id": "pose_standing_front",
    "resolution": "2K",
    "aspect_ratio": "3:4"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done
04Read the status code + error body instead of silently failing
bash
# -w pulls out the HTTP status without polluting the JSON body.
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{ "product_type": "dress" }')

BODY=$(echo "$RESPONSE" | sed '$d')
STATUS=$(echo "$RESPONSE" | tail -1)

case "$STATUS" in
  200|202)
    echo "$BODY" | jq '.data' ;;
  402)
    echo "Out of credits" ; echo "$BODY" | jq '.error' ;;
  429)
    RETRY=$(echo "$BODY" | jq -r '.error.retry_after')
    echo "Rate limited — retry in ${RETRY}s" ;;
  *)
    echo "Error $STATUS" ; echo "$BODY" | jq '.error' ;;
esac

Por qué esta estructura

Por qué cURL sigue siendo la forma más rápida de verificar una API

  • Zero install — cURL ships with every major OS
  • Pairs with `jq` for scripted pipelines (CI, cron, bash hooks)
  • Ideal for smoke-testing endpoints before wiring them into code
  • All code in this page copy-pastes into any POSIX shell

Qué no hace

Honest caveats

  • cURL's polling loop blocks your terminal — move to Node/Python for parallel workers
  • No streaming parser for the result; you fetch the final URL when the job is done
  • Windows Command Prompt users should run WSL or PowerShell's curl.exe wrapper

Preguntas de otros desarrolladores

Questions other developers ask

¿Existe una herramienta CLI de Photta?+

Aún no — pero cURL junto con un wrapper de bash de quince líneas te da casi lo mismo. La documentación prioriza los ejemplos de cURL porque cada lenguaje puede ejecutar un subproceso y la shell es el denominador común en los pipelines de CI.

¿Necesito jq para usar la API?+

No estrictamente — pero los pipelines automatizados son mucho más fáciles con él. jq te permite extraer `.data.id`, `.data.status` y `.data.output_url` de la respuesta JSON sin tener que analizarla a mano. Instálalo con `brew install jq` en macOS o `apt install jq` en Debian/Ubuntu.

¿Cómo me autentico con curl?+

Añade `-H "Authorization: Bearer $PHOTTA_API_KEY"` a cada solicitud. Mantén la clave en una variable de entorno, nunca la pongas directamente en un script que subas al repositorio. `curl --oauth2-bearer` también funciona, pero la forma del header explícito es más clara en la documentación y los logs.

¿Puedo usar scripts basados en curl en producción?+

Para cargas masivas puntuales y tareas programadas (cron), sí — miles de equipos gestionan actualizaciones de catálogos así. Para una aplicación persistente, suele ser mejor un lenguaje real porque obtienes una gestión de errores, reintentos y observabilidad adecuada. Los ejemplos de curl en esta página siguen siendo válidos incluso después de portarlos a Node o Python; la estructura de la solicitud es la misma.

¿Cómo realizo el polling desde un bucle de bash?+

Usa `for i in $(seq 1 120); do … ; sleep 3; done` con la verificación de estado dentro del bucle. Sal cuando `.data.status` sea `completed` o `failed`. El ejemplo de código en esta página muestra el patrón exacto, incluyendo un límite superior estricto para que un trabajo atascado no bloquee el script para siempre.

¿Cómo leo las respuestas de error en curl?+

Usa `curl -w "\n%{http_code}"` para capturar el código de estado HTTP junto con el cuerpo JSON. Decide según el estado: 402 para créditos insuficientes, 429 para límites de tasa (respeta el valor Retry-After), 5xx para errores transitorios del servidor. El cuerpo del error siempre tiene un campo `error.code` y `error.message`.

cURL · API de Try-On Virtual

Crea una cuenta y obtén una API key

Exporta `PHOTTA_API_KEY`, haz un POST a `https://ai.photta.app/api/v1/tryon/apparel` con el cuerpo JSON correcto, captura el ID de generación, luego haz un bucle de `curl … /tryon/apparel/:id` cada 3 segundos hasta que `data.status` cambie a `completed` — típicamente en 1.5 a 4 minutos. Combínalo con `jq` para extraer la URL de salida de la respuesta final.

API de Try-On Virtual con cURL — Photta | Photta