Изображение в GLB через curl
Небольшого Bash-сценария достаточно, чтобы отправить изображение, следить за одной задачей до завершения и скачать GLB. Специальный TO3D CLI не нужен; генерация и риггинг — разные задачи.
Проверено 27 сентября 2026
Перед началом
Создайте 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 и сохраните возвращённый 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
Опрашивайте endpoint с тем же id. В успешном ответе есть output.model_file — постоянный URL, доступный без API-ключа.
- Ждите пять секунд между проверками и ограничьте цикл подходящим для вашей задачи числом попыток.
- Не отправляйте запрос заново при тайм-ауте цикла; позже проверьте исходный 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. Создавайте задачу Skin Tokens только при необходимости humanoid-скелета и опрашивайте её тем же способом.
- Отправьте task_type rig на /api/skin_tokens/tasks.
- Укажите в input.model URL GLB или GLB в base64 и выберите имена костей 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-запросы с backoff, сохраняя тот же id задачи.
- 400 означает неверную форму запроса или входные данные; 401 означает отсутствующий или недействительный ключ.
- Ответ 404 для задачи доступен только аккаунту, создавшему эту задачу.
curl -sS "$BASE/api/trellis/tasks/$TASK_ID" -H "x-api-key: $TO3D_KEY" | jq '{id,status,output,error}'