视频

创建动作检测任务

POST/videos/motion_detections

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

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└model

string(Model)

Motion detection model to run for this request. Available values: `turbo`, `pro`.

Default: `turbo`

└input_video

required

string(Input Video)

Source video input from which a segment will be cut for motion tracking and capture. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└start_time_seconds

required

number(Start Time Seconds)[0..∞]

Start time, in seconds from the beginning of the video, for the segment to track.

└duration_seconds

required

number(Duration Seconds)

Duration, in seconds, of the segment to cut and track.

└bboxes

number[][] | null

Optional bounding boxes `[[x1, y1, x2, y2], ...]` from `/video/pose_detections` used to restrict tracking to specific people. When omitted, the task returns motion results for all detected people in the selected segment.

└bboxes[]

array

└bboxes[][]

number

└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)

Motion asset URIs extracted from the selected tracked segment(s). Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

required

object(MotionDetectionMetadata)

Top-level metadata returned by the ``motion-detection`` task handler.Captures the result of tracking selected people inside a time windowand exporting their motions plus matching media clips.``tracked_bboxes`` and ``tracked_indexes`` only contain entries forbboxes that were successfully matched and produced BVH output. Theirlengths are always equal to ``len(motions)``.

└video

required

string(Video)

Original input video URI.

└requested_bboxes

required

array(Requested Bboxes)

Bounding boxes `[[x1, y1, x2, y2], ...]` requested by the client for tracking.

└requested_bboxes[]

array

└requested_bboxes[][]

number

└tracked_bboxes

required

array(Tracked Bboxes)

Bounding boxes that were successfully matched and produced BVH output. Length equals ``len(motions)``.

└tracked_bboxes[]

array

└tracked_bboxes[][]

number

└tracked_indexes

required

array(Tracked Indexes)

Indexes into ``requested_bboxes`` for entries that were successfully matched. Length equals ``len(motions)``.

└tracked_indexes[]

integer

└query_start_time_seconds

required

number(Query Start Time Seconds)[0..∞]

Requested segment start time, in seconds, from the original input video.

└query_duration_seconds

required

number(Query Duration Seconds)

Requested segment duration, in seconds, from the API input.

└effective_query_duration_seconds

required

number(Effective Query Duration Seconds)

Effective segment duration, in seconds, after worker-side alignment or expansion.

└video_clip

string | null

Stored video clip created for the tracked segment, when available. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└audio_clip

string | null

Stored audio clip created for the tracked segment, when available. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└fps

required

number(Fps)

Frame rate detected from the input video.

└motions

required

array(Motions)

Per-person tracked motion segment metadata.

└motions[]

any

└downloads

any[] | null

Temporary download links for related source and extracted 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/videos/motion_detections \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_video": "<input_video>",
      "start_time_seconds": 0,
      "duration_seconds": 0
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": [],
  "metadata": {}
}

获取动作检测任务

GET/videos/motion_detections/{task_uuid}

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

参数

名称	位置	必填	类型	说明
task_uuid	path	是	string	Task UUID returned when the motion detection 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)

Motion asset URIs extracted from the selected tracked segment(s). Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└result[]

string

└metadata

required

object(MotionDetectionMetadata)

Top-level metadata returned by the ``motion-detection`` task handler.Captures the result of tracking selected people inside a time windowand exporting their motions plus matching media clips.``tracked_bboxes`` and ``tracked_indexes`` only contain entries forbboxes that were successfully matched and produced BVH output. Theirlengths are always equal to ``len(motions)``.

└video

required

string(Video)

Original input video URI.

└requested_bboxes

required

array(Requested Bboxes)

Bounding boxes `[[x1, y1, x2, y2], ...]` requested by the client for tracking.

└requested_bboxes[]

array

└requested_bboxes[][]

number

└tracked_bboxes

required

array(Tracked Bboxes)

Bounding boxes that were successfully matched and produced BVH output. Length equals ``len(motions)``.

└tracked_bboxes[]

array

└tracked_bboxes[][]

number

└tracked_indexes

required

array(Tracked Indexes)

Indexes into ``requested_bboxes`` for entries that were successfully matched. Length equals ``len(motions)``.

└tracked_indexes[]

integer

└query_start_time_seconds

required

number(Query Start Time Seconds)[0..∞]

Requested segment start time, in seconds, from the original input video.

└query_duration_seconds

required

number(Query Duration Seconds)

Requested segment duration, in seconds, from the API input.

└effective_query_duration_seconds

required

number(Effective Query Duration Seconds)

Effective segment duration, in seconds, after worker-side alignment or expansion.

└video_clip

string | null

Stored video clip created for the tracked segment, when available. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└audio_clip

string | null

Stored audio clip created for the tracked segment, when available. Returned asset URIs are relative paths that can be reused directly in compatible input fields.

└fps

required

number(Fps)

Frame rate detected from the input video.

└motions

required

array(Motions)

Per-person tracked motion segment metadata.

└motions[]

any

└downloads

any[] | null

Temporary download links for related source and extracted 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/videos/motion_detections/<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": [],
  "metadata": {}
}

创建姿态检测任务

POST/videos/pose_detections

检测已上传或已存储视频资产中特定帧的人体姿态。

请求体

Content-Type: application/jsonRequired: true

Request Body Schema

application/json

└input_video

required

string(Input Video)

Source video input that contains the frame to detect. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└time_seconds

required

number(Time Seconds)[0..∞]

Requested time in seconds from the start of the video for which pose detection should run.

└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)

Per-person pose detections extracted from the requested video frame.

└result[]

object(PoseDetectionResultItem)

└id

required

integer(Id)

Detection-local person identifier for the frame.

└confidence

required

number(Confidence)[0..1]

Model confidence score for the detected person.

└bbox_xyxy

required

array(Bbox Xyxy)[4..4] items

Bounding box in pixel coordinates as `(x1, y1, x2, y2)`.

└bbox_xywh

required

array(Bbox Xywh)[4..4] items

Bounding box in pixel coordinates as `(x, y, width, height)`.

└keypoints_2d

required

array(Keypoints 2D)

2D joint and face landmarks projected in image coordinates.

└keypoints_2d[]

any

└keypoints_3d

any[] | null

Optional 3D joint and face landmarks returned by the detector.

└keypoints_3d[]

any

└metadata

required

object(PoseDetectionMetadata)

└video

required

string(Video)

Original input video URI.

└query_time_seconds

required

number(Query Time Seconds)[0..∞]

Requested timestamp in seconds from the API input before frame rounding or snapping.

└frame_time_seconds

required

number(Frame Time Seconds)[0..∞]

Resolved frame timestamp in seconds.

└frame_index

required

integer(Frame Index)[0..∞]

Zero-based frame index used for inference.

└fps

required

number(Fps)

Frame rate detected from the input video.

└total_frames

required

integer(Total Frames)[0..∞]

Total number of frames in the input video.

└image_width

required

integer(Image Width)

Extracted frame width in pixels.

└image_height

required

integer(Image Height)

Extracted frame height in pixels.

└id_scope

string | null

Identifier namespace used for `result[*].id` values.

└visualization_image

string | null

Stored visualization image for the analyzed frame, when available. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└downloads

any[] | null

Temporary download links for related source or extracted 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/videos/pose_detections \
  -X POST \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "input_video": "<input_video>",
      "time_seconds": 0
    }'

Response 200 OK

{
  "task_uuid": "<task_uuid>",
  "task_type": "<task_type>",
  "model": "<model>",
  "status": "<taskstatus>",
  "created_at": 0,
  "completed_at": 0,
  "result": [],
  "metadata": {}
}

获取姿态检测任务

GET/videos/pose_detections/{task_uuid}

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

参数

名称	位置	必填	类型	说明
task_uuid	path	是	string	Task UUID returned when the pose detection 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)

Per-person pose detections extracted from the requested video frame.

└result[]

object(PoseDetectionResultItem)

└id

required

integer(Id)

Detection-local person identifier for the frame.

└confidence

required

number(Confidence)[0..1]

Model confidence score for the detected person.

└bbox_xyxy

required

array(Bbox Xyxy)[4..4] items

Bounding box in pixel coordinates as `(x1, y1, x2, y2)`.

└bbox_xywh

required

array(Bbox Xywh)[4..4] items

Bounding box in pixel coordinates as `(x, y, width, height)`.

└keypoints_2d

required

array(Keypoints 2D)

2D joint and face landmarks projected in image coordinates.

└keypoints_2d[]

any

└keypoints_3d

any[] | null

Optional 3D joint and face landmarks returned by the detector.

└keypoints_3d[]

any

└metadata

required

object(PoseDetectionMetadata)

└video

required

string(Video)

Original input video URI.

└query_time_seconds

required

number(Query Time Seconds)[0..∞]

Requested timestamp in seconds from the API input before frame rounding or snapping.

└frame_time_seconds

required

number(Frame Time Seconds)[0..∞]

Resolved frame timestamp in seconds.

└frame_index

required

integer(Frame Index)[0..∞]

Zero-based frame index used for inference.

└fps

required

number(Fps)

Frame rate detected from the input video.

└total_frames

required

integer(Total Frames)[0..∞]

Total number of frames in the input video.

└image_width

required

integer(Image Width)

Extracted frame width in pixels.

└image_height

required

integer(Image Height)

Extracted frame height in pixels.

└id_scope

string | null

Identifier namespace used for `result[*].id` values.

└visualization_image

string | null

Stored visualization image for the analyzed frame, when available. Accepts an existing relative URI path, a base64-encoded file payload (including `data:` URLs), or an HTTP/HTTPS file URL.

└downloads

any[] | null

Temporary download links for related source or extracted 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/videos/pose_detections/<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": [],
  "metadata": {}
}