主题模式
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。 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | V2Fun 3D Flash 或 V2Fun 3D Pro。 |
prompt | string | 文本模式 | 物体描述;单图和多视图模式改用对应图片字段。 |
input_image | string | 单图模式 | 单张图片输入。 |
input_images | object | 多视图模式 | 多视图图片对象。 |
input_images.front | string | 多视图模式 | 正视图。 |
input_images.left | string | null | 否 | 左视图。 |
input_images.back | string | null | 否 | 背视图。 |
input_images.right | string | null | 否 | 右视图。 |
with_texture | boolean | 否 | 是否同时生成纹理;默认 false。 |
hd_texture | boolean | 否 | 是否提高纹理分辨率;默认 false,需开启 with_texture。 |
pbr_texture | boolean | 否 | 是否生成 PBR 材质贴图;默认 false,需开启 with_texture。 |
options | object | null | 否 | 任务执行选项。 |
options.block | boolean | null | 否 | 使用 false。 |
options.priority | integer | null | 否 | 高级选项,0–255,值越大越优先。 |
图片输入可使用 HTTP/HTTPS URL、Base64 文件内容(含 data URL)或服务商可访问的已有相对资源 URI。
1.2 响应
创建成功返回 HTTP 201,表示任务已被受理并将在后台执行;响应包含用于查询的 task_uuid。以下列出排队受理结构,完成结果见“查询 3D 模型生成任务”。
| 字段 | 类型 | 说明 |
|---|---|---|
task_uuid | string | 任务 ID,用于后续查询。 |
task_type | string | mesh-generate |
model | string | 平台模型名,如 V2Fun 3D Flash。 |
status | string | 任务状态。201 排队受理示例为 QUEUED。 |
created_at | integer | 创建时间,Unix 秒。 |
queue_position | integer | null | 可选;当前排队位置,≥0,不保证实际执行顺序。 |
estimated_queue_time | number | null | 可选;预计等待秒数,≥0。 |
request_id | string | 本次 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_uuid | path | string | 是 | 替换为创建接口返回的 task_uuid。 |
2.2 响应
HTTP 200 · application/json。响应随任务状态变化。
| 字段 | 类型 | 说明 |
|---|---|---|
task_uuid | string | 创建接口返回的任务 ID。 |
task_type | string | mesh-generate |
model | string | 平台模型名,如 V2Fun 3D Flash。 |
status | string | QUEUED、PROCESSING、COMPLETED、FAILED。 |
created_at | integer | 创建时间,Unix 秒。 |
queue_position | integer | null | 排队时可能返回;≥0。 |
estimated_queue_time | number | null | 排队时可能返回的预计等待秒数;≥0。 |
progress | number | 处理中可能返回;范围 0–1。 |
completed_at | integer | 成功完成时间,Unix 秒;COMPLETED 时返回。 |
failed_at | integer | null | FAILED 时可能返回的失败时间,Unix 秒。 |
result | string[] | COMPLETED 时的产物 URI 数组;失败时也可能存在部分输出,类型以实际响应为准。 |
metadata | object[] | null | 成功结果的附加信息,见下表。 |
request_id | string | 本次查询的 AIPing 请求追踪 ID。 |
2.2.1 metadata 数组元素
| 字段 | 类型 | 说明 |
|---|---|---|
reference_images | string[] | null | 生成或贴图时使用的参考图片 URI。 |
preview_image | string | null | 模型预览图 URI。 |
t_pose_model | string | null | 流程产出时返回的绑定 T-pose 模型 URI。 |
mesh_info | object | null | 网格统计或渲染相关信息。 |
preview_video | string | null | 模型预览视频 URI。 |
downloads | array | null | 当前模型及相关资源的临时下载描述。 |
| 字段 | 类型 | 说明 |
|---|---|---|
downloads[].asset_path | string | 关联的资源 URI,可与 result 或元数据中的 URI 对应。 |
downloads[].download_url | string | 临时 HTTP 下载链接。 |
downloads[].download_expires_at | integer | 链接到期时间,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。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | V2Fun 视频动捕 Turbo 或 V2Fun 视频动捕 Pro。 |
input_video | string | 是 | 输入视频:HTTP/HTTPS URL、Base64 文件内容(含 data URL)或服务商可访问的已有相对资源 URI。 |
start_time_seconds | number | 是 | 片段起点,单位秒,≥0。 |
duration_seconds | number | 是 | 待处理片段时长,单位秒。 |
bboxes | number[][] | null | 否 | 人物框,形如 [[x1, y1, x2, y2], ...],用于限定跟踪对象。 |
options | object | null | 否 | 任务执行选项。 |
options.block | boolean | null | 否 | 使用 false。 |
options.priority | integer | null | 否 | 高级选项,0–255,值越大越优先。 |
3.2 响应
创建成功返回 HTTP 201,表示任务已被受理并将在后台执行;响应包含用于查询的 task_uuid。完成结果见下一查询接口。
| 字段 | 类型 | 说明 |
|---|---|---|
task_uuid | string | 任务 ID,用于后续查询。 |
task_type | string | motion-detection |
model | string | 平台模型名,如 V2Fun 视频动捕 Turbo。 |
status | string | 任务状态。201 排队受理示例为 QUEUED。 |
created_at | integer | 创建时间,Unix 秒。 |
queue_position | integer | null | 可选;当前排队位置,≥0,不保证实际执行顺序。 |
estimated_queue_time | number | null | 可选;预计等待秒数,≥0。 |
request_id | string | 本次 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_uuid | path | string | 是 | 替换为创建接口返回的 task_uuid。 |
4.2 响应
HTTP 200 · application/json。排队和处理中只返回对应阶段字段。
| 字段 | 类型 | 说明 |
|---|---|---|
task_uuid | string | 创建接口返回的任务 ID。 |
task_type | string | motion-detection |
model | string | 平台模型名,如 V2Fun 视频动捕 Turbo。 |
status | string | QUEUED、PROCESSING、COMPLETED、FAILED。 |
created_at | integer | 创建时间,Unix 秒。 |
queue_position | integer | null | 排队时可能返回;≥0。 |
estimated_queue_time | number | null | 排队时可能返回的预计等待秒数;≥0。 |
progress | number | 处理中可能返回;范围 0–1。 |
completed_at | integer | 成功完成时间,Unix 秒;COMPLETED 时返回。 |
failed_at | integer | null | FAILED 时可能返回的失败时间,Unix 秒。 |
result | string[] | COMPLETED 时的产物 URI 数组;失败时也可能存在部分输出,类型以实际响应为准。 |
metadata | object | 成功结果的附加信息,见下表。 |
request_id | string | 本次查询的 AIPing 请求追踪 ID。 |
4.2.1 metadata 对象
| 字段 | 类型 | 说明 |
|---|---|---|
video | string | 原输入视频的资源 URI。 |
requested_bboxes | number[][] | 请求指定的人物框。 |
tracked_bboxes | number[][] | 成功匹配并生成 BVH 的人物框;数量与 motions 相同。 |
tracked_indexes | integer[] | 成功匹配项在 requested_bboxes 中的索引;数量与 motions 相同。 |
query_start_time_seconds | number | 请求片段的起点,秒,≥0。 |
query_duration_seconds | number | 请求的片段时长,秒。 |
effective_query_duration_seconds | number | 服务商对齐或扩展后实际处理的片段时长,秒。 |
video_clip | string | null | 处理片段对应的视频资源 URI。 |
audio_clip | string | null | 处理片段对应的音频资源 URI。 |
fps | number | 检测到的输入视频帧率。 |
motions | array | 各人物的动作片段元数据;官方参考未展开元素内部字段。 |
downloads | array | null | 源视频、动作和片段等相关资源的临时下载描述。 |
| 字段 | 类型 | 说明 |
|---|---|---|
downloads[].asset_path | string | 关联的资源 URI,可与 result 或元数据中的 URI 对应。 |
downloads[].download_url | string | 临时 HTTP 下载链接。 |
downloads[].download_expires_at | integer | 链接到期时间,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 为执行失败。