GUIDES / API-ABLAUF

Bild mit curl zu GLB

Ein kleiner Bash-Ablauf reicht: Bild senden, dieselbe Aufgabe bis zum Ende verfolgen und das GLB laden. Es gibt kein spezielles TO3D-CLI; Erzeugung und Rigging sind getrennte Aufgaben.

API-Referenz lesen API-Key holen

Geprüft am 27. September 2026

Vorbereitung

Erstelle im Dashboard einen API-Key und speichere ihn in einer Umgebungsvariable. Die Bild-URL muss erreichbar sein; image-to-3d akzeptiert URL oder base64 für PNG, JPEG und GIF bis 128 MB.

Verwende für jede Anfrage den Header x-api-key.
Eine Generierungsaufgabe gibt 202 zurück und wechselt von pending über processing zu succeeded, failed oder canceled.
Eine fehlgeschlagene oder abgebrochene Aufgabe wird automatisch erstattet, wenn der Anbieter sie nicht abschließt.

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

Ein Bild senden

Sende die Bild-URL an Trellis und speichere die zurückgegebene id. Abfragen und Download verwenden diese id und erzeugen keine weitere kostenpflichtige Aufgabe.

Sende task_type image-to-3d.
Setze die Bild-URL unter input.image.
Behandle die Antwort-id als opak und übernimm sie exakt wie zurückgegeben.

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"

Abfragen und GLB laden

Frage den Endpoint mit derselben id ab. Bei Erfolg enthält output.model_file eine dauerhafte URL, die ohne API-Key geladen werden kann.

Warte zwischen den Prüfungen fünf Sekunden und begrenze die Schleife passend zu deinem Auftrag.
Sende bei einem Schleifen-Timeout nicht erneut; prüfe später die ursprüngliche Task-ID.
Prüfe die ersten vier Bytes der Datei auf glTF, bevor du sie an einen Viewer oder eine Engine übergibst.

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 ]

Ergebnis optional riggen

Rigging ist eine zweite Anfrage für das geladene GLB. Erzeuge nur bei einem benötigten Humanoid-Skelett eine Skin-Tokens-Aufgabe und frage sie gleich ab.

Sende task_type rig an /api/skin_tokens/tasks.
Setze input.model auf die GLB-URL oder ein Base64-GLB und wähle die Knochennamen original, mixamo oder ue5.
Der Rig-Endpunkt liefert output.model_file, sobald seine eigene Aufgabe abgeschlossen ist.

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

Fehler und Zeitüberschreitung

Ein vorübergehender 503 oder ein lokales Timeout ist kein Grund für eine zweite Aufgabe. Zuerst die ursprüngliche id abfragen und Status und Fehler lesen.

Wiederhole vorübergehende HTTP-Anfragen mit Backoff und behalte dieselbe Task-ID.
400 bedeutet, dass Anfrageform oder Eingabe ungültig ist; 401 bedeutet, dass der Schlüssel fehlt oder ungültig ist.
Eine 404-Antwort für eine Aufgabe gilt nur für das Konto, das sie erstellt hat.

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