动作检索

用自然语言在动作库中搜索最匹配的 3D 动画资产。返回结果包含 BVH 动作文件路径、动作预览视频及描述，所有 asset_path 可直接传入动画重定向接口使用。

典型应用场景

• 智能动画工作流：根据剧本台词自动匹配角色动作，替代手动翻库
• 动作库管理：通过语义搜索快速定位所需资产，支持中英文描述

推荐工作流

1. 描述动作 → 用自然语言描述想要的动作，如 "a person waves goodbye"
2. 获取结果 → 返回最匹配的动作列表，含 asset_path、preview_video、title
3. 预览确认 → 通过 preview_video 确认动作效果
4. 串联使用 → 将 asset_path 直接传入动画重定向接口，驱动自定义角色

本页使用的 API 参考 POST /motions/retrievals

基础示例

cURL

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

JavaScript

const response = await fetch('https://api.v2fun.ai/api/v1/motions/retrievals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $V2FUN_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text_prompt": "dance"
  }),
});
const data = await response.json();

Python

import requests

resp = requests.post(
    'https://api.v2fun.ai/api/v1/motions/retrievals',
    headers={
        'Authorization': 'Bearer $V2FUN_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        "text_prompt": "dance"
    },
)
print(resp.json())

Java

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String body = "{\"text_prompt\":\"dance\"}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.v2fun.ai/api/v1/motions/retrievals"))
    .header("Authorization", "Bearer $V2FUN_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

核心用例

语义化动作搜索

用自然语言描述动作意图，系统返回最匹配的动作资产列表，每条结果附带可直接复用的 asset_path 及动作预览视频。

cURL

curl -X POST 'https://api.v2fun.ai/api/v1/motions/retrievals' \
  -H 'Authorization: Bearer $V2FUN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "text_prompt": "running at medium speed on flat ground"
    }'

JavaScript

const response = await fetch('https://api.v2fun.ai/api/v1/motions/retrievals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $V2FUN_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text_prompt": "running at medium speed on flat ground"
  }),
});
const data = await response.json();

Python

import requests

resp = requests.post(
    'https://api.v2fun.ai/api/v1/motions/retrievals',
    headers={
        'Authorization': 'Bearer $V2FUN_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        "text_prompt": "running at medium speed on flat ground"
    },
)
print(resp.json())

Java

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String body = "{\"text_prompt\":\"running at medium speed on flat ground\"}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.v2fun.ai/api/v1/motions/retrievals"))
    .header("Authorization", "Bearer $V2FUN_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

返回结果示例：

{
  "status": "COMPLETED",
  "result": [
    "motions/h3d/bvh/00035389_000.bvh",
    "motions/h3d/bvh/00037695_000.bvh",
    "motions/h3d/bvh/00079075_000.bvh"
  ],
  "metadata": [
    {
      "asset_id": "0049f145-1379-45da-8d22-45aafa43b642",
      "asset_path": "motions/h3d/bvh/00035389_000.bvh",
      "preview_video": "/videos/h3d/Mariel_00035389_000_0001-0100.mp4",
      "title": "h3d_00035389",
      "description": "a person runs forward at a medium speed.",
      "available_formats": ["bvh", "vmd"]
    }
  ]
}

asset_path 可直接作为动画重定向接口（input_motion）的输入值。