动作与动画

创建动作检索任务

POST/motions/retrievals

通过自然语言描述在动作库中搜索匹配动作。

请求体

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`.

响应

通用错误码说明请查看：错误处理。

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

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

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/motions/retrievals/{task_uuid}

获取动作检索任务的当前状态或最终结果。

参数

名称	位置	必填	类型	说明
task_uuid	path	是	string	Task UUID returned when the motion search job was created.

响应

通用错误码说明请查看：错误处理。

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

立即体验

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": []
}

创建动画重定向任务

POST/motions/animations

将动作文件应用到已绑定骨骼的 3D 模型上。

请求体

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`.

响应

通用错误码说明请查看：错误处理。

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

也可能返回 201，表示任务已接受并在后台异步执行。使用响应体中的 task_uuid 轮询对应的 GET 端点获取结果。了解同步 vs 异步 →

立即体验

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/motions/animations/{task_uuid}

获取动画重定向任务的当前状态或最终输出。

参数

名称	位置	必填	类型	说明
task_uuid	path	是	string	Task UUID returned when the animation job was created.

响应

通用错误码说明请查看：错误处理。

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

立即体验

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": []
}