Motion Retrieval

Search the motion library with natural language to find the best-matching 3D animation assets. Results include BVH file paths, preview videos, and descriptions — all asset_path values can be passed directly into the Animation API.

Typical Application Scenarios

• Smart Animation Pipeline: Auto-match character actions from screenplay text, no manual library browsing
• Motion Library Management: Quickly locate assets via semantic search in Chinese or English

Recommended Workflow

1. Describe the motion → use natural language, e.g. "a person waves goodbye"
2. Get results → returns matching assets with asset_path, preview_video, and title
3. Preview → confirm the motion via preview_video
4. Chain to animation → pass asset_path directly as input_motion in the Animation API

API Reference used on this page POST /motions/retrievals

Basic Examples

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());

Core Use Cases

Semantic Motion Search

Describe a motion in natural language; the system returns the best-matching asset list, each with a reusable asset_path and a motion preview video.

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());

Example response:

{
  "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 can be used directly as the input_motion value in the Animation API.