# AI3D API v2 Tripo animation operations

Use these operations to check whether a model can be rigged, rig a model, or apply a preset animation. The convenience `POST /v2/auto-rig` endpoint detects rig type, applies the matching rig, and optionally retargets that type's documented default animations as one asynchronous wallet-billed job. Biped defaults are the five-clip first-person shooter pack; quadruped, hexapod, and octopod defaults use `walk`; serpentine and aquatic defaults use `march`. Tripo documents no default preset for avian rigs. Manual rig and retarget jobs (`tripo-rig`, `tripo-retarget`) use `POST /v2/jobs`. The free customer riggability utility is `POST /v2/rig-check`; its metadata appears under `utilities` in both the `tripo-rig` and `tripo-auto-rig` entries from `GET /v2/models` when those models are enabled. The direct Tripo gateway routes described below stay operator-only.

For public low-poly test assets, `GET /v2/debug/latest-low-poly-idle` returns the latest public retargeted output for the latest public low-poly rig. If an idle preset is not available for that rig, the endpoint promotes its supported locomotion preset to the `idle` role: biped `walk`, quadruped `quadruped:walk`, hexapod `hexapod:walk`, octopod `octopod:walk`, serpentine `serpentine:march`, or aquatic `aquatic:march`. The response includes `animation_preset` and `animation_fallback` so clients can see which motion was returned. The endpoint and its artifact URL require no authentication and only expose public outputs whose source chain is known low-poly.

- AI3D API reference: <https://api.ai3d.dev/v2/docs>
- Tripo animation endpoints: <https://developers.tripo3d.ai/en/docs/animations-rig-check>, <https://developers.tripo3d.ai/en/docs/animations-rig>, <https://developers.tripo3d.ai/en/docs/animations-retarget>
- All operations are asynchronous. Poll `GET /v2/tripo/tasks/{task_id}` for status and output.
- Direct passthrough access: these gateway endpoints require an operator-issued AI3D API key. Customer account keys are rejected because provider usage is not settled against customer wallet credits. Never place an operator key in a browser, mobile app, or other public client.

## Customer riggability check

`POST /v2/rig-check` is a free customer utility associated with `tripo-rig` and `tripo-auto-rig`. It follows `TRIPO_OPERATIONS_MODE`: it is disabled when the mode is `off`, limited to `TRIPO_OPERATIONS_CANARY_ACCOUNTS` in `canary`, and listed in the corresponding catalog entries in `on` mode. Use a customer bearer key with write permission and the relevant model ID in its allowlist, or use the signed-in session in the browser playground. The endpoint allows 10 checks per minute per account.

Send exactly one of your own completed Tripo generation job ID or a public HTTPS GLB URL (up to 150 MB):

```json
{
  "source_job_id": "<completed AI3D Tripo job UUID>"
}
```

```json
{
  "model_url": "https://example.com/model.glb"
}
```

The response contains `riggable`, `rig_type`, and `recommended_rig_model`; it does not expose a Tripo task ID. The check is optional: a `tripo-rig` job can be submitted directly.

## Operator gateway: check riggability

`POST /v2/tripo/animations/rig-check` accepts a JSON `input` containing exactly one Tripo task ID, uploaded file token, or public model URL. Rig-check documents **GLB** input only, up to 150 MB. Use this check before auto-rigging.

```json
{
  "input": "task_abc123"
}
```

The completed task returns `output.riggable` and, when riggable, a recommended `output.rig_type`: `biped`, `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine`, or `aquatic`.

## Auto rig

`POST /v2/tripo/animations/rig` accepts `input` as a Tripo task ID, uploaded file token, or public model URL. Supported source formats are **GLB, GLTF, FBX, OBJ, and STL**, up to 150 MB. The file-format restriction for rig-check is narrower; use GLB when running the recommended check first.

Optional JSON fields:

- `model`: `v1.0-20240301` (biped) or `v2.5-20260210` (non-biped creature rigs).
- `rig_type`: `biped`, `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine`, or `aquatic`.
- `spec`: `tripo` or `mixamo` bone naming.
- `out_format`: `glb` (default) or `fbx`.

```json
{
  "input": "task_abc123",
  "model": "v2.5-20260210",
  "rig_type": "quadruped",
  "spec": "tripo",
  "out_format": "glb"
}
```

The completed task returns the rigged model URL in `output.model_url`.

## Retarget a preset animation

`POST /v2/tripo/animations/retarget` requires `input` to be the Tripo task ID of a rigged model. Supply exactly one of `animation` (one preset ID) or `animations` (a list of preset IDs). Presets depend on the rig model version and rig type; use Tripo's animation-retarget reference for the full list.

Optional fields include `out_format` (`glb` by default or `fbx`), `bake_animation` (default `true`, only effective for GLB), `export_with_geometry` (default `true`), and `animate_in_place` (default `false`).

```json
{
  "input": "task_rigged123",
  "animation": "preset:walk",
  "out_format": "glb",
  "bake_animation": true
}
```

The completed task returns the animated model URL in `output.model_url`.

## Authentication and task polling

Send an operator-issued AI3D API key as `Authorization: Bearer <AI3D_API_KEY>` and `Content-Type: application/json`. Each successful submission returns `data.task_id`. Poll it with:

```http
GET /v2/tripo/tasks/task_abc123
```

The provider reports usage on the final task result. Direct gateway operations spend the shared Tripo account and are not charged to a customer AI3D wallet.