Motions

Create a motion retrieval task

POST/motions/retrievals

Search the motion library with a natural-language description.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└text_prompt

required

string(Text Prompt)

Natural-language motion query used to search the motion library.

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Ordered list of motion asset paths that best match the query. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

RetrievalResultMetadata[] | null

Additional metadata describing each matched motion asset.

└metadata[]

object(RetrievalResultMetadata)

└asset_id

string | null

Identifier of the matched motion asset.

└asset_path

string | null

Storage path of the matched motion asset. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└preview_video

string | null

Preview video URI for the matched motion asset. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└title

string | null

Display title of the matched motion asset.

└description

string | null

Human-readable description of the matched motion asset.

└available_formats

string[] | null

Available file formats for the matched motion asset.

└available_formats[]

string

└downloads

any[] | null

Temporary download links for the matched motion asset. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/motions/retrievals \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "text_prompt": "<text_prompt>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Get a motion retrieval task

GET/motions/retrievals/{task_uuid}

Retrieve the current status or final result of a motion retrieval task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the motion search job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

Ordered list of motion asset paths that best match the query. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

RetrievalResultMetadata[] | null

Additional metadata describing each matched motion asset.

└metadata[]

object(RetrievalResultMetadata)

└asset_id

string | null

Identifier of the matched motion asset.

└asset_path

string | null

Storage path of the matched motion asset. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└preview_video

string | null

Preview video URI for the matched motion asset. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└title

string | null

Display title of the matched motion asset.

└description

string | null

Human-readable description of the matched motion asset.

└available_formats

string[] | null

Available file formats for the matched motion asset.

└available_formats[]

string

└downloads

any[] | null

Temporary download links for the matched motion asset. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

Try It

curl https://api.v2fun.ai/api/v1/motions/retrievals/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Create an animation retargeting task

POST/motions/animations

Apply a motion file to a rigged 3D model.

Request Body

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└input_model

required

string(Input Model)

Rigged 3D model input that will receive the animation. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└input_motion

required

string(Input Motion)

Motion file input to retarget onto the rigged 3D model. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└fps

number(Fps)

Target frames per second for the animated output. Use -1 to keep the source frame rate.

Default: `-1`

└options

TaskRequestOptions | null

Optional task execution controls for the task

└block

boolean | null

When true, wait for task completion and return the terminal response immediately. When false, return a task reference for polling.

└priority

integer | null[0..255]

Task dispatch priority within this client. Larger values are consumed earlier. Must not exceed the client's `mq_priority`. When omitted, defaults to the client's `mq_priority`.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

This endpoint may also return 201 when the task is accepted for asynchronous execution. Use the task_uuid from the response body to poll the corresponding GET endpoint for the result. Sync vs async →

Try It

curl https://api.v2fun.ai/api/v1/motions/animations \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_model": "<input_model>",
      "input_motion": "<input_motion>"
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}

Get an animation retargeting task

GET/motions/animations/{task_uuid}

Retrieve the current status or final output of an animation retargeting task.

Parameters

Name	In	Required	Type	Description
task_uuid	path	Yes	string	Task UUID returned when the animation job was created.

Responses

For standard error codes, see Error Handling.

Response Schema

200application/json

└task_uuid

required

string(Task Uuid)

Unique identifier for the task

└task_type

required

string(Task Type)

Logical task category used by the backend pipeline.

└model

required

string(Model)

Model or worker name assigned to the task.

└status

required

string(TaskStatus)

Enum: QUEUED PROCESSING COMPLETED FAILED

└created_at

required

integer(Created At)

Unix timestamp, in seconds, when the task was created.

└completed_at

required

integer(Completed At)

Unix timestamp, in seconds, when the task finished successfully.

└result

required

array(Result)

List of generated 3D model URIs. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

Model3dMetadata[] | null

Additional metadata for each generated 3D model.

└metadata[]

object(Model3dMetadata)

└reference_images

string[] | null

Reference image URIs used to generate or texture the model, in the order they were consumed. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└reference_images[]

string

└preview_image

string | null

Preview render URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└t_pose_model

string | null

Rigged T-pose model URI, when the pipeline produces one. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└mesh_info

object | null

Mesh statistics or renderer metadata for the generated model.

└preview_video

string | null

Preview render video URI for the generated 3D model. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└downloads

any[] | null

Temporary download links for related generated assets. Flattened list of presigned HTTP download descriptors for every URI returned in `result` or this object.

└downloads[]

any

Try It

curl https://api.v2fun.ai/api/v1/motions/animations/<task_uuid> \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": []
}