Skip to content

V2Fun API 文档 ​

1. 创建 3D 模型生成任务 ​

http
POST /api/v1/multimodal/v2fun/3d_models/meshes

通过文本、单张图片或多视角图片集生成 3D 网格模型。

1.1 请求体 ​

Content-Type: application/json。按下列三种模式选择一种输入。

模式必填输入说明
文本生成prompt用文字描述目标物体。
单图生成input_image提供一张参考图片。
多视图生成input_images.front提供正视图,可补充 left、back、right。
字段类型必填说明
modelstring是V2Fun 3D Flash 或 V2Fun 3D Pro。
promptstring文本模式物体描述;单图和多视图模式改用对应图片字段。
input_imagestring单图模式单张图片输入。
input_imagesobject多视图模式多视图图片对象。
input_images.frontstring多视图模式正视图。
input_images.leftstring | null否左视图。
input_images.backstring | null否背视图。
input_images.rightstring | null否右视图。
with_textureboolean否是否同时生成纹理;默认 false。
hd_textureboolean否是否提高纹理分辨率;默认 false,需开启 with_texture。
pbr_textureboolean否是否生成 PBR 材质贴图;默认 false,需开启 with_texture。
optionsobject | null否任务执行选项。
options.blockboolean | null否使用 false。
options.priorityinteger | null否高级选项,0–255,值越大越优先。

图片输入可使用 HTTP/HTTPS URL、Base64 文件内容(含 data URL)或服务商可访问的已有相对资源 URI。

1.2 响应 ​

创建成功返回 HTTP 201,表示任务已被受理并将在后台执行;响应包含用于查询的 task_uuid。以下列出排队受理结构,完成结果见“查询 3D 模型生成任务”。

字段类型说明
task_uuidstring任务 ID,用于后续查询。
task_typestringmesh-generate
modelstring平台模型名,如 V2Fun 3D Flash。
statusstring任务状态。201 排队受理示例为 QUEUED。
created_atinteger创建时间,Unix 秒。
queue_positioninteger | null可选;当前排队位置,≥0,不保证实际执行顺序。
estimated_queue_timenumber | null可选;预计等待秒数,≥0。
request_idstring本次 AIPing 请求的追踪 ID。

1.3 示例 ​

创建示例 ​

  • 文本生成:完整 curl。
bash
curl -X POST "https://testacs.aiping.cn/api/v1/multimodal/v2fun/3d_models/meshes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "V2Fun 3D Flash",
  "prompt": "一位宇航员",
  "options": {
    "block": false
  }
}'
  • 单图生成:在相同 POST 请求中,将 JSON 正文替换为以下内容。
json
{
  "model": "V2Fun 3D Pro",
  "input_image": "https://example.com/reference-image.png",
  "options": {
    "block": false
  }
}
  • 多视图生成:在相同 POST 请求中,将 JSON 正文替换为以下内容。
json
{
  "model": "V2Fun 3D Pro",
  "input_images": {
    "front": "https://example.com/front.png",
    "left": "https://example.com/left.png",
    "back": "https://example.com/back.png",
    "right": "https://example.com/right.png"
  },
  "with_texture": true,
  "options": {
    "block": false
  }
}

响应 ​

HTTP 201 Created · application/json

json
{
  "task_uuid": "<task_uuid>",
  "task_type": "mesh-generate",
  "model": "V2Fun 3D Flash",
  "status": "QUEUED",
  "created_at": 0,
  "queue_position": 0,
  "estimated_queue_time": 0,
  "request_id": "<request_id>"
}

2. 查询 3D 模型生成任务 ​

http
GET /api/v1/multimodal/v2fun/3d_models/meshes/{task_uuid}

获取 3D 模型生成任务的当前状态或最终输出。

2.1 路径参数 ​

名称位置类型必填说明
task_uuidpathstring是替换为创建接口返回的 task_uuid。

2.2 响应 ​

HTTP 200 · application/json。响应随任务状态变化。

字段类型说明
task_uuidstring创建接口返回的任务 ID。
task_typestringmesh-generate
modelstring平台模型名,如 V2Fun 3D Flash。
statusstringQUEUED、PROCESSING、COMPLETED、FAILED。
created_atinteger创建时间,Unix 秒。
queue_positioninteger | null排队时可能返回;≥0。
estimated_queue_timenumber | null排队时可能返回的预计等待秒数;≥0。
progressnumber处理中可能返回;范围 0–1。
completed_atinteger成功完成时间,Unix 秒;COMPLETED 时返回。
failed_atinteger | nullFAILED 时可能返回的失败时间,Unix 秒。
resultstring[]COMPLETED 时的产物 URI 数组;失败时也可能存在部分输出,类型以实际响应为准。
metadataobject[] | null成功结果的附加信息,见下表。
request_idstring本次查询的 AIPing 请求追踪 ID。

2.2.1 metadata 数组元素 ​

字段类型说明
reference_imagesstring[] | null生成或贴图时使用的参考图片 URI。
preview_imagestring | null模型预览图 URI。
t_pose_modelstring | null流程产出时返回的绑定 T-pose 模型 URI。
mesh_infoobject | null网格统计或渲染相关信息。
preview_videostring | null模型预览视频 URI。
downloadsarray | null当前模型及相关资源的临时下载描述。
字段类型说明
downloads[].asset_pathstring关联的资源 URI,可与 result 或元数据中的 URI 对应。
downloads[].download_urlstring临时 HTTP 下载链接。
downloads[].download_expires_atinteger链接到期时间,Unix 秒;以返回值为准。

result、preview_image 等 URI 用于标识资源;下载时使用对应的 download_url,并留意 download_expires_at。

2.3 示例 ​

查询示例 ​

bash
curl -X GET "https://testacs.aiping.cn/api/v1/multimodal/v2fun/3d_models/meshes/<task_uuid>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

响应 ​

HTTP 200 OK · application/json。下例以占位 URI 展示已完成结构;实际产物数量、格式和可选元数据以返回值为准。

json
{
  "task_uuid": "<task_uuid>",
  "task_type": "mesh-generate",
  "model": "V2Fun 3D Flash",
  "status": "COMPLETED",
  "created_at": 0,
  "completed_at": 0,
  "result": ["<mesh_asset_uri>"],
  "metadata": [
    {
      "reference_images": [],
      "preview_image": null,
      "t_pose_model": null,
      "mesh_info": null,
      "preview_video": null,
      "downloads": [
        {
          "asset_path": "<mesh_asset_uri>",
          "download_url": "https://example.com/download/mesh-asset",
          "download_expires_at": 0
        }
      ]
    }
  ],
  "request_id": "<request_id>"
}

QUEUED 为排队,PROCESSING 为处理中,COMPLETED 为已完成,FAILED 为执行失败。查询成功不等于生成成功。

3. 创建视频动捕任务 ​

http
POST /api/v1/multimodal/v2fun/videos/motion_detections

从输入视频中截取片段,追踪一个或多个检测到的人物,生成动作捕捉输出。

3.1 请求体 ​

Content-Type: application/json。

字段类型必填说明
modelstring是V2Fun 视频动捕 Turbo 或 V2Fun 视频动捕 Pro。
input_videostring是输入视频:HTTP/HTTPS URL、Base64 文件内容(含 data URL)或服务商可访问的已有相对资源 URI。
start_time_secondsnumber是片段起点,单位秒,≥0。
duration_secondsnumber是待处理片段时长,单位秒。
bboxesnumber[][] | null否人物框,形如 [[x1, y1, x2, y2], ...],用于限定跟踪对象。
optionsobject | null否任务执行选项。
options.blockboolean | null否使用 false。
options.priorityinteger | null否高级选项,0–255,值越大越优先。

3.2 响应 ​

创建成功返回 HTTP 201,表示任务已被受理并将在后台执行;响应包含用于查询的 task_uuid。完成结果见下一查询接口。

字段类型说明
task_uuidstring任务 ID,用于后续查询。
task_typestringmotion-detection
modelstring平台模型名,如 V2Fun 视频动捕 Turbo。
statusstring任务状态。201 排队受理示例为 QUEUED。
created_atinteger创建时间,Unix 秒。
queue_positioninteger | null可选;当前排队位置,≥0,不保证实际执行顺序。
estimated_queue_timenumber | null可选;预计等待秒数,≥0。
request_idstring本次 AIPing 请求的追踪 ID。

3.3 示例 ​

创建示例 ​

以下示例使用公开视频 URL;实际调用时,input_video 需为有权使用、且服务商可以访问的视频地址。

bash
curl -X POST "https://testacs.aiping.cn/api/v1/multimodal/v2fun/videos/motion_detections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "V2Fun 视频动捕 Turbo",
  "input_video": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4",
  "start_time_seconds": 0,
  "duration_seconds": 3,
  "options": {
    "block": false
  }
}'

响应 ​

HTTP 201 Created · application/json

json
{
  "task_uuid": "<task_uuid>",
  "task_type": "motion-detection",
  "model": "V2Fun 视频动捕 Turbo",
  "status": "QUEUED",
  "created_at": 0,
  "queue_position": 0,
  "estimated_queue_time": 0,
  "request_id": "<request_id>"
}

4. 查询视频动捕任务 ​

http
GET /api/v1/multimodal/v2fun/videos/motion_detections/{task_uuid}

获取动作检测任务的当前状态或最终输出。

4.1 路径参数 ​

名称位置类型必填说明
task_uuidpathstring是替换为创建接口返回的 task_uuid。

4.2 响应 ​

HTTP 200 · application/json。排队和处理中只返回对应阶段字段。

字段类型说明
task_uuidstring创建接口返回的任务 ID。
task_typestringmotion-detection
modelstring平台模型名,如 V2Fun 视频动捕 Turbo。
statusstringQUEUED、PROCESSING、COMPLETED、FAILED。
created_atinteger创建时间,Unix 秒。
queue_positioninteger | null排队时可能返回;≥0。
estimated_queue_timenumber | null排队时可能返回的预计等待秒数;≥0。
progressnumber处理中可能返回;范围 0–1。
completed_atinteger成功完成时间,Unix 秒;COMPLETED 时返回。
failed_atinteger | nullFAILED 时可能返回的失败时间,Unix 秒。
resultstring[]COMPLETED 时的产物 URI 数组;失败时也可能存在部分输出,类型以实际响应为准。
metadataobject成功结果的附加信息,见下表。
request_idstring本次查询的 AIPing 请求追踪 ID。

4.2.1 metadata 对象 ​

字段类型说明
videostring原输入视频的资源 URI。
requested_bboxesnumber[][]请求指定的人物框。
tracked_bboxesnumber[][]成功匹配并生成 BVH 的人物框;数量与 motions 相同。
tracked_indexesinteger[]成功匹配项在 requested_bboxes 中的索引;数量与 motions 相同。
query_start_time_secondsnumber请求片段的起点,秒,≥0。
query_duration_secondsnumber请求的片段时长,秒。
effective_query_duration_secondsnumber服务商对齐或扩展后实际处理的片段时长,秒。
video_clipstring | null处理片段对应的视频资源 URI。
audio_clipstring | null处理片段对应的音频资源 URI。
fpsnumber检测到的输入视频帧率。
motionsarray各人物的动作片段元数据;官方参考未展开元素内部字段。
downloadsarray | null源视频、动作和片段等相关资源的临时下载描述。
字段类型说明
downloads[].asset_pathstring关联的资源 URI,可与 result 或元数据中的 URI 对应。
downloads[].download_urlstring临时 HTTP 下载链接。
downloads[].download_expires_atinteger链接到期时间,Unix 秒;以返回值为准。

result 中存放动作资源 URI,可通过 metadata.downloads 对应的 download_url 下载。

4.3 示例 ​

查询示例 ​

bash
curl -X GET "https://testacs.aiping.cn/api/v1/multimodal/v2fun/videos/motion_detections/<task_uuid>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

响应 ​

HTTP 200 OK · application/json。metadata 的内部字段在本示例中省略,按上表读取实际响应。

json
{
  "task_uuid": "<task_uuid>",
  "task_type": "motion-detection",
  "model": "V2Fun 视频动捕 Turbo",
  "status": "COMPLETED",
  "created_at": 0,
  "completed_at": 0,
  "result": ["<motion_asset_uri>"],
  "metadata": {},
  "request_id": "<request_id>"
}

QUEUED 为排队,PROCESSING 为处理中,COMPLETED 为已完成,FAILED 为执行失败。