Skip to main content

Tripo-Animation Retargeting

Tripo Animation Retargeting applies preset animations to a rigged 3D model. Up to 5 animations are supported per task.

This document applies only to the China (Beijing) region. Use an API key from this region.

Prerequisites

  1. Enable the service: Go to the Alibaba Cloud Model Studio console, search for "Tripo", find the Tripo model card, and click Enable Now. In the dialog box, confirm the authorization.
  2. Configure your API key: Select a region, get an API key, and then configure the API key as an environment variable.
  3. Prepare a preceding task: Create a task by using Tripo-Auto Rigging with spec not set to mixamo. After the task succeeds, pass its task_id in original_model_task_id.

HTTP calls

The API uses asynchronous calls. The process involves two steps: create a task and then poll for the result.

Step 1: Create a task

China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation Replace {WorkspaceId} with your actual workspace ID.
  • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
  • For guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Request headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
model string (Required)The model name. Fixed value: Tripo/Tripo-AnimationRetarget.input object (Required)The model input.

Properties

original_model_task_id string (Required)The preceding task ID. Only Tripo-Auto Rigging tasks are supported. Pass the task_id returned when the task is created. The system automatically uses the rigged model output by the task.
  • The preceding task must have succeeded.
  • The account that makes this call must be the same as the account of the preceding task. Referencing a task created by another account returns a 400 error.
  • Models rigged with the mixamo specification (spec) cannot be used for animation retargeting.
parameters object (Optional)The animation retargeting parameters.

Properties

animations array[string] (Conditionally required)The list of preset animation names. Up to 5. Billed by the number of animations. This parameter and animation are mutually exclusive. Specify only one of them.Each element must be a preset animation name with the preset: prefix (for example, preset:walk). Names are case-sensitive. A name not in the list returns a 400 error at task creation, and no credits are deducted.For the full list of animation names, see Animation names.animation string (Conditionally required)A single preset animation name. The requirements are the same as those for animations. This parameter and animations are mutually exclusive. Specify only one of them. This is a legacy parameter. It is counted as one animation and billed the same as passing one animation in animations.out_format string (Optional)The output format. Default value: glb. Valid values:
  • glb: Binary glTF, suitable for the web.
  • fbx: FBX, suitable for DCC tools and game engines.
bake_animation boolean (Optional)Specifies whether to bake animations. This parameter is deprecated. Passing it does not return an error, has no effect, and incurs no charges. It is retained only for backward compatibility. You do not need to pass it.export_with_geometry boolean (Optional)Specifies whether to include geometry in the export. Default value: true.animate_in_place boolean (Optional)Specifies whether to play animations in place. Default value: false. If set to true, the model does not move during the animation.
  • Single animation
  • Multiple animations
  • Non-humanoid skeleton
# The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "Tripo/Tripo-AnimationRetarget",
    "input": {
        "original_model_task_id": "ca51d54a-ffba-4ecc-8e42-xxxxxx"
    },
    "parameters": {
        "animations": ["preset:walk"],
        "out_format": "fbx"
    }
}'

Response parameters

output objectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query the task result

China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Polling recommendation: We recommend using a polling mechanism: query 10 seconds after submitting the task, and then every 15 to 30 seconds.
  • Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
  • Task ID validity: The task ID is valid for 24 hours. After this period, you can no longer query the result, and the API returns the task status as UNKNOWN.
  • RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure asynchronous task callbacks.
  • More operations: To query tasks in batches or cancel a task, see Manage Asynchronous Tasks.

Request parameters

Request headers
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
Path parameters
task_id string (Required)The ID of the task.
  • Query task result
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours. Replace {WorkspaceId} with your actual workspace ID.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
  • PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
  • The status of the first query is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the URL of the retargeted 3D model.
  • If the status is FAILED, check the error message and retry.
  • If the status is CANCELED, the task was canceled. To continue, submit a new task.
  • If the status is UNKNOWN, the task does not exist or its status is unknown. This can occur if the task_id does not exist or has exceeded its 24-hour validity period.
submit_time stringThe time when the task was submitted. Format: YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task started running. Format: YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. Format: YYYY-MM-DD HH:mm:ss.SSS.results arrayThe list of retargeting results. Returned only when task_status is SUCCEEDED. Each URL is a signed temporary link that is valid for 2 hours. Please download it promptly.

Properties

model_url stringThe URL of the retargeted 3D model.
code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectThe output statistics. Returned only when the task succeeds.

Properties

3d_task_type stringThe task type. Fixed to animation-retarget for animation retargeting.credits_consumed integerThe credits consumed by the task, billed by the number of animations. The number of animations is the number of non-empty elements in animations. If you use animation, it is counted as one animation.
  • Task succeeded
  • Task failed
  • Task query expired
{
    "request_id": "36a8ae2d-e929-9315-8394-xxxxxx",
    "output": {
        "task_id": "00195645-f254-41bd-8354-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-10-19 12:56:48.349",
        "scheduled_time": "2026-10-19 12:56:48.399",
        "end_time": "2026-10-19 12:57:04.742",
        "results": [
            {
                "model_url": "https://openapi.cdn.tripo3d.com/xxxx/tripo_retarget_xxxx.fbx?auth_key=xxxx"
            }
        ]
    },
    "usage": {
        "3d_task_type": "animation-retarget",
        "credits_consumed": 10
    }
}

Animation names

The following names are the valid values of the parameters.animations and parameters.animation parameters. Names must include the preset: prefix and are case-sensitive.

Common animations

  • preset:idle: Idle
  • preset:walk: Walk
  • preset:run: Run
  • preset:jump: Jump
  • preset:climb: Climb
  • preset:dive: Dive
  • preset:slash: Slash
  • preset:shoot: Shoot
  • preset:hurt: Hurt
  • preset:fall: Fall
  • preset:turn: Turn

Non-humanoid skeletons

Non-humanoid skeletons support only the following names, in the format preset:<body type>:<action>.
  • Quadruped (quadruped): preset:quadruped:walk, preset:quadruped:catwalk
  • Aquatic (aquatic): preset:aquatic:march
  • Serpentine (serpentine): preset:serpentine:march
  • Hexapod (hexapod): preset:hexapod:walk
  • Octopod (octopod): preset:octopod:walk

Humanoid skeletons

Action names for humanoid skeletons (biped) can be written in two equivalent ways: preset:<action> or preset:biped:<action>. For example, preset:walk has the same effect as preset:biped:walk.
  • preset:afraid, preset:agree, preset:angry_01, preset:angry_02, preset:angry_03
  • preset:basketball_shot, preset:blade_wraparound_test, preset:bow, preset:box_01, preset:box_02, preset:box_03
  • preset:cast_a_spell, preset:cheer, preset:chop, preset:clap, preset:climb, preset:complain_01, preset:complain_02, preset:cpr, preset:cross_body_crunch, preset:crossover_dribble, preset:cry
  • preset:dance_01, preset:dance_02, preset:dance_03, preset:dance_04, preset:dance_05, preset:dance_06, preset:defeat_02, preset:defeat_03, preset:depressed, preset:dig, preset:dive, preset:dribble
  • preset:fall, preset:fire, preset:flee_01, preset:flee_02, preset:flip, preset:fold_arms, preset:football_catch, preset:football_pass, preset:football_save, preset:freaky, preset:frightened, preset:front_kick_01, preset:front_kick_02, preset:frustrated_01, preset:frustrated_02
  • preset:golf, preset:greet_01, preset:greet_02, preset:greet_03, preset:greet_04
  • preset:heart_pose, preset:hit_to_body_01, preset:hit_to_body_02, preset:hit_to_head, preset:hit_to_side, preset:hit_to_stomach, preset:hug, preset:hurt
  • preset:idle
  • preset:jump, preset:jump_down, preset:jump_rope_01, preset:jump_rope_02
  • preset:laugh_01, preset:laugh_02, preset:lift_heavy, preset:look_around
  • preset:make_a_call_01, preset:make_a_call_02
  • preset:pitch_baseball, preset:play_mobile_game, preset:play_video_game, preset:press-up
  • preset:run, preset:run_upstairs
  • preset:scared_01, preset:scared_02, preset:scratch, preset:shoot, preset:shovel, preset:sing_01, preset:sing_02, preset:sing_03, preset:sing_04, preset:sit, preset:slash, preset:sob, preset:standing_relax, preset:surf, preset:swagger, preset:swim, preset:sword_judgment_test
  • preset:turn
  • preset:victory_celebration, preset:volleyball
  • preset:wait, preset:walk, preset:warm_up, preset:wave_goodbye_01, preset:wave_goodbye_02

Error messages

If the model call fails and returns an error message, see Error messages for solutions.