GUÍAS / FLUJO DE API

De imagen a GLB con curl

Un pequeño flujo de Bash basta para enviar una imagen, seguir la misma tarea hasta que termine y descargar el GLB. No hace falta un CLI de TO3D y la generación y el rigging son tareas separadas.

Leer la referencia de API Obtener una clave de API

Verificado el 27 de septiembre de 2026

Antes de empezar

Crea una clave de API en el panel y guárdala en una variable de entorno. La URL de imagen debe ser accesible para el servicio; image-to-3d acepta URL o base64 de PNG, JPEG y GIF hasta 128 MB.

Usa el encabezado x-api-key en cada solicitud.
Una tarea de generación devuelve 202 y pasa de pending a processing y después a succeeded, failed o canceled.
Una tarea fallida o cancelada se reembolsa automáticamente si el proveedor no la completa.

export TO3D_KEY='your_api_key'
export TO3D_IMAGE_URL='https://example.com/photo.png'
BASE='https://api.to3d.app'

Envía una imagen

Publica la URL de imagen en Trellis. Guarda primero el id devuelto; las consultas y la descarga usan ese id y no crean otra tarea de pago.

Envía task_type image-to-3d.
Coloca la URL de la imagen en input.image.
Trata el id de la respuesta como opaco y consérvalo exactamente como se devuelve.

TASK_JSON=$(curl -sS --fail-with-body "$BASE/api/trellis/tasks" \
  -H "x-api-key: $TO3D_KEY" -H 'Content-Type: application/json' \
  -d "$(jq -cn --arg image "$TO3D_IMAGE_URL" '{task_type: "image-to-3d", input: {image: $image}}')")
TASK_ID=$(jq -er '.id' <<<"$TASK_JSON")
printf 'Task: %s\n' "$TASK_ID"

Consulta y descarga el GLB

Consulta el endpoint con el mismo id. Una respuesta exitosa contiene output.model_file, una URL persistente que se puede descargar sin la clave.

Espera cinco segundos entre comprobaciones y limita el bucle según tu trabajo.
No vuelvas a enviar la solicitud si el bucle agota el tiempo; consulta después el id de la tarea original.
Comprueba que los cuatro primeros bytes del archivo sean glTF antes de entregarlo a un visor o motor.

MODEL_URL=''
for ((attempt = 0; attempt < 120; attempt++)); do
  STATUS_JSON=$(curl -sS --fail-with-body "$BASE/api/trellis/tasks/$TASK_ID" -H "x-api-key: $TO3D_KEY")
  STATUS=$(jq -er '.status' <<<"$STATUS_JSON")
  case "$STATUS" in
    succeeded) MODEL_URL=$(jq -er '.output.model_file' <<<"$STATUS_JSON"); break ;;
    failed|canceled) jq '{id,status,error}' <<<"$STATUS_JSON" >&2; exit 1 ;;
    pending|processing) sleep 5 ;;
  esac
done
[ -n "$MODEL_URL" ] || { echo "Timed out; keep the task id" >&2; exit 1; }
curl -fsSL "$MODEL_URL" -o model.glb
[ "$(head -c 4 model.glb)" = glTF ]

Riggea el resultado de forma opcional

El rigging es una segunda petición sobre el GLB descargado. Crea una tarea Skin Tokens solo si necesitas un esqueleto humanoide y consúltala con el mismo patrón.

Envía task_type rig a /api/skin_tokens/tasks.
Establece input.model como la URL del GLB o un GLB en base64 y elige los nombres de huesos original, mixamo o ue5.
El endpoint de rigging devuelve output.model_file cuando termina su propia tarea.

curl -sS --fail-with-body "$BASE/api/skin_tokens/tasks" \
  -H "x-api-key: $TO3D_KEY" -H 'Content-Type: application/json' \
  -d '{"task_type":"rig","input":{"model":"https://storage.to3d.app/tasks/example/model.glb","bone_names":"mixamo"}}'

Fallos y tiempos agotados

Un 503 transitorio o un tiempo agotado local no justifican crear una segunda tarea. Consulta primero el id original y lee su estado y error.

Reintenta las solicitudes HTTP transitorias con backoff y conserva el mismo id de tarea.
400 indica que la forma de la solicitud o la entrada no es válida; 401 indica que falta la clave o no es válida.
Una respuesta 404 de tarea está limitada a la cuenta que creó la tarea.

curl -sS "$BASE/api/trellis/tasks/$TASK_ID" -H "x-api-key: $TO3D_KEY" | jq '{id,status,output,error}'