가이드 / API 워크플로

curl로 이미지를 GLB로 변환

작은 Bash 워크플로만으로 이미지를 제출하고 같은 작업이 끝날 때까지 확인한 다음 GLB를 다운로드할 수 있습니다. 전용 TO3D CLI는 필요하지 않으며 생성과 리깅은 별도 작업입니다.

2026년 9월 27일 확인

시작하기 전에

대시보드에서 API 키를 만들고 환경 변수에 보관하세요. 이미지 URL은 서비스에서 접근 가능해야 합니다. image-to-3d는 URL 또는 base64 PNG, JPEG, GIF를 받으며 최대 128 MB입니다.

모든 요청에 x-api-key 헤더를 사용하세요.
생성 작업은 202를 반환하고 pending에서 processing을 거쳐 succeeded, failed 또는 canceled로 이동합니다.
프로바이더가 작업을 완료하지 못하면 failed 또는 canceled 작업은 자동으로 환불됩니다.

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

이미지 하나 제출

이미지 URL을 Trellis에 POST합니다. 반환된 id를 먼저 저장하세요. 이후 확인과 다운로드는 같은 id를 사용하며 유료 작업을 새로 만들지 않습니다.

task_type image-to-3d를 전송하세요.
이미지 URL을 input.image에 넣으세요.
응답 id를 불투명한 값으로 취급하고 반환된 그대로 정확히 보관하세요.

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"

확인하고 GLB 다운로드

같은 작업 id로 엔드포인트를 확인하세요. 성공 응답의 output.model_file은 API 키 없이 받을 수 있는 영구 URL입니다.

확인 사이에 5초를 기다리고 작업에 맞는 횟수로 루프를 제한하세요.
루프가 시간 초과되어도 다시 제출하지 말고 나중에 원래 task id를 확인하세요.
뷰어 또는 엔진에 전달하기 전에 파일의 첫 네 바이트가 glTF인지 확인하세요.

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 ]

선택적으로 결과 리깅

리깅은 다운로드한 GLB에 대한 두 번째 요청입니다. humanoid 골격이 필요할 때만 Skin Tokens 작업을 만들고 같은 방식으로 확인하세요.

/api/skin_tokens/tasks에 task_type rig를 전송하세요.
input.model에 GLB URL 또는 base64 GLB를 설정하고 original, mixamo 또는 ue5 본 이름을 선택하세요.
리그 엔드포인트는 자체 작업이 끝난 뒤 output.model_file을 반환합니다.

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

실패와 타임아웃

일시적인 503이나 로컬 확인 타임아웃 때문에 두 번째 작업을 만들지 마세요. 원래 id를 먼저 확인해 상태와 오류 기록을 읽으세요.

일시적인 HTTP 요청은 백오프로 재시도하되 같은 task id를 유지하세요.
400은 요청 형식이나 입력이 잘못되었다는 뜻이고, 401은 키가 없거나 유효하지 않다는 뜻입니다.
작업의 404 응답은 해당 작업을 만든 계정으로 범위가 제한됩니다.

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