GUIDES / WORKFLOW API

Image vers GLB avec curl

Un petit workflow Bash suffit pour envoyer une image, suivre la même tâche jusqu’à sa fin et télécharger le GLB. Aucun CLI TO3D dédié n’est nécessaire ; génération et rigging sont deux tâches distinctes.

Lire la référence API Obtenir une clé API

Vérifié le 27 septembre 2026

Avant de commencer

Créez une clé API dans le tableau de bord et gardez-la dans une variable d’environnement. L’URL de l’image doit être accessible ; image-to-3d accepte une URL ou du base64 PNG, JPEG ou GIF jusqu’à 128 MB.

Utilisez l’en-tête x-api-key pour chaque requête.
Une tâche de génération renvoie 202 et passe de pending à processing, puis à succeeded, failed ou canceled.
Une tâche échouée ou annulée est automatiquement remboursée si le fournisseur ne la mène pas à terme.

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

Envoyer une image

POSTez l’URL à Trellis et enregistrez l’id renvoyé. Les requêtes de statut et le téléchargement utilisent cet id sans créer une autre tâche payante.

Envoyez task_type image-to-3d.
Placez l’URL de l’image dans input.image.
Traitez l’id de la réponse comme opaque et conservez-le exactement tel qu’il est renvoyé.

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"

Interroger et télécharger le GLB

Interrogez l’endpoint avec le même id. Une réponse réussie contient output.model_file, une URL persistante téléchargeable sans clé API.

Attendez cinq secondes entre les vérifications et limitez la boucle selon votre travail.
Ne soumettez pas à nouveau si la boucle expire ; consultez plus tard l’id de la tâche d’origine.
Vérifiez les quatre premiers octets du fichier pour glTF avant de le donner à un visualiseur ou à un moteur.

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 ]

Rigging facultatif

Le rigging est une seconde requête sur le GLB téléchargé. Créez une tâche Skin Tokens seulement si vous avez besoin d’un squelette humanoïde, puis interrogez-la de la même façon.

Envoyez task_type rig à /api/skin_tokens/tasks.
Définissez input.model sur l’URL du GLB ou un GLB en base64 et choisissez les noms d’os original, mixamo ou ue5.
L’endpoint de rigging renvoie output.model_file lorsque sa propre tâche est terminée.

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"}}'

Erreurs et délais

Un 503 temporaire ou un délai local ne justifie pas une seconde tâche. Consultez d’abord l’id d’origine et lisez son statut et son erreur.

Réessayez les requêtes HTTP transitoires avec un backoff en conservant le même id de tâche.
400 signifie que la forme de la requête ou l’entrée est invalide ; 401 signifie que la clé manque ou est invalide.
Une réponse 404 pour une tâche est limitée au compte qui l’a créée.

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