ガイド / 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'

画像を1枚送信

画像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 秒にし、用途に合った上限でループを制限します。
ループがタイムアウトしても再送信せず、後で元のタスク id を確認します。
ビューアーやエンジンに渡す前に、ファイルの先頭 4 バイトが 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に対する2回目のリクエストです。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やローカルの確認タイムアウトで2つ目のタスクを作らないでください。まず元のidを確認し、状態とエラーの記録を読みます。

一時的な HTTP エラーはバックオフ付きで再試行し、同じタスク id を使い続けます。
400 はリクエスト形式または入力が無効、401 はキーがないか無効であることを示します。
タスクの 404 レスポンスは、そのタスクを作成したアカウントに限定されます。

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