GUIAS / FLUXO DA API

Imagem para GLB com curl

Um pequeno fluxo Bash envia a imagem, acompanha a mesma tarefa até terminar e baixa o GLB. Não é preciso um CLI da TO3D; geração e rigging são tarefas separadas.

Ler referência da API Obter uma chave de API

Verificado em 27 de setembro de 2026

Antes de começar

Crie uma chave de API no painel e guarde-a em uma variável de ambiente. A URL da imagem precisa ser acessível pelo serviço; image-to-3d aceita URL ou base64 de PNG, JPEG e GIF até 128 MB.

Use o cabeçalho x-api-key em todas as requisições.
Uma tarefa de geração retorna 202 e passa de pending para processing e depois para succeeded, failed ou canceled.
Uma tarefa failed ou canceled é reembolsada automaticamente quando o provedor não a conclui.

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

Envie uma imagem

Envie a URL da imagem para Trellis e guarde o id retornado. A consulta e o download usam esse id e não criam outra tarefa paga.

Envie task_type image-to-3d.
Coloque a URL da imagem em input.image.
Trate o id da resposta como opaco e mantenha-o exatamente como foi retornado.

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"

Consulte e baixe o GLB

Consulte o endpoint com o mesmo id. Uma resposta bem-sucedida contém output.model_file, uma URL durável que pode ser baixada sem a chave.

Aguarde cinco segundos entre as verificações e limite o loop de acordo com o seu trabalho.
Não envie novamente quando o loop atingir o tempo limite; consulte depois o id da tarefa original.
Verifique os quatro primeiros bytes do arquivo para glTF antes de entregá-lo a um visualizador ou 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 ]

Faça rigging opcionalmente

Rigging é uma segunda requisição para o GLB baixado. Crie uma tarefa Skin Tokens apenas quando precisar de um esqueleto humanoide e consulte-a do mesmo modo.

Envie task_type rig para /api/skin_tokens/tasks.
Defina input.model como a URL do GLB ou um GLB em base64 e escolha os nomes de ossos original, mixamo ou ue5.
O endpoint de rigging retorna output.model_file quando sua própria tarefa termina.

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

Falhas e timeouts

Um 503 transitório ou um timeout local não justificam uma segunda tarefa. Consulte primeiro o id original e leia seu estado e erro.

Tente novamente as requisições HTTP transitórias com backoff, mantendo o mesmo id da tarefa.
400 significa que o formato da requisição ou a entrada é inválida; 401 significa que a chave está ausente ou inválida.
Uma resposta 404 de tarefa é limitada à conta que criou a tarefa.

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