# W-Agent API

W-Agent provides public APIs for person identity recognition, emotion recognition, video parsing, gait sequence parsing, human 2D/3D keypoints, and Object Search.

## Capabilities

- Parse video into person sequences.
- Parse tracked person image sequences.
- Extract gait, face, and ReID feature vectors.
- Compare same-type feature vectors by dot product similarity.
- Return ReID structured attributes.
- Return human 2D/3D keypoints.
- Find targets in an image from a text prompt through Object Search.
- Support registered API Key calls.
- Support anonymous x402 payment calls.

## Agent Task Selection

- If the goal is "same person or not", use sequence parsing and compare gait_feature, face_feature, or reid_feature with same-type dot product. Do not use raw image similarity.
- If the input is a video and the goal is stable person sequences, prefer local video-to-sequence demos: decode locally, detect, track, crop, write one folder per sequence, then upload each folder to the Sequence API.
- If the goal is 2D/3D keypoints, upload sequence frames first, then call POST /v1/sequences/{task_id}/gait-pose.
- If the goal is finding targets in one image from text, use Object Search.
- Registered calls use Authorization: Bearer <api_key> on registered routes and are paid from account balance.
- Anonymous calls use public routes, receive HTTP 402 payment_context, sign an x402 payment, then retry the same HTTP request.

Core rule: identity and pose APIs operate on tracked person sequences. A full video is one possible source for generating those sequences.

Task decision table:

- Same person or not: use POST /v1/sequences/{task_id}/parse, then dot-product same-type gait_feature, face_feature, or reid_feature.
- Full video to identity features: use local video-to-sequence demo plus Sequence API, or use POST /v1/videos for server-side asynchronous parsing.
- Video to every person's 2D/3D keypoints: use local video-to-sequence demo plus POST /v1/sequences/{task_id}/gait-pose for each sequence.
- Text-prompt object detection in one image: use POST /v1/object-search.
- Raw image visual similarity: not a W-Agent identity workflow.

## Discovery References

- OpenAPI: https://www.w-agent.cn/api/openapi.json
- GitHub examples: https://github.com/w-agent-ai/api-example
- Task recipes: https://github.com/w-agent-ai/api-example/tree/main/recipes
- MCP config example: https://github.com/w-agent-ai/api-example/blob/main/mcp-config.example.json
- MCP endpoint: https://www.w-agent.cn/api/mcp

## Sequence Result Shape

Sequence parsing returns a sequences array even when the client uploads one input track. This is intentional. A tracker can switch identity when people cross or occlude each other, so one track ID may start on person A and later follow person B. The backend checks the uploaded track with ReID features; if it detects an ID switch or mixed-person frames, it splits the input at the switch point and returns multiple clean single-person output sequences. Ambiguous frames may be dropped.

## Base URL

https://www.w-agent.cn/api

Public API base URLs:

- Mainland China: https://www.w-agent.cn/api
- Overseas entry: https://www.h-agent.ai/api

Overseas redirects to w-agent.cn are expected. Do not guess https://api.w-agent.cn;
that hostname is not documented and may fail TLS hostname verification. The API
path prefix is /api on the public website, for example
https://www.w-agent.cn/api/v1/sequences.

## Authentication

Registered users call APIs with:

Authorization: Bearer <api_key>

Anonymous agents use public endpoints and x402 payment challenges.

MCP task tools are currently for registered API Key users. Anonymous x402 payment is not part of the MCP protocol flow here; anonymous agents should call the public HTTP APIs, receive HTTP 402 payment_context, sign the x402 payment, and retry the HTTP request.

## MCP

MCP Streamable HTTP endpoint:

https://www.w-agent.cn/api/mcp

## Machine Readable References

- OpenAPI: https://www.w-agent.cn/api/openapi.json
- Agent Markdown: https://www.w-agent.cn/api/.well-known/w-agent.md

## Main Endpoints

- POST /v1/sequences
- PUT /v1/uploads/{task_id}/{index}
- POST /v1/sequences/{task_id}/parse
- POST /v1/sequences/{task_id}/gait-pose
- POST /v1/videos
- PUT /v1/video-uploads/{task_id}?token=<upload_token>
- POST /v1/videos/{task_id}/complete
- GET /v1/videos/{task_id}
- GET /v1/videos/{task_id}/result
- POST /v1/object-search
- POST /v1/public/object-search/trial
- POST /v1/public/videos
- PUT /v1/video-uploads/{task_id}?token=<upload_token>
- POST /v1/public/videos/{task_id}/settle-phase1
- GET /v1/public/videos/{task_id}
- GET /v1/public/videos/{task_id}/result
- POST /v1/public/videos/{task_id}/settle-phase2
- POST /v1/public/sequences
- PUT /v1/uploads/{task_id}/{index}?token=<upload_token>
- POST /v1/public/sequences/{task_id}/parse
- POST /v1/public/sequences/{task_id}/gait-pose
- GET /v1/public/sequences/{task_id}/result

## Sequence Quickstart

Goal: parse a local image sequence and compare identities.

1. POST /v1/sequences with {"frame_count": <number_of_images>}.
2. PUT each image to the returned uploads[].upload_url.
3. Keep uploads[].object_key.
4. POST /v1/sequences/{task_id}/parse with {"frames":[{"index":0,"object_key":"..."}]}.
5. Read features from response.sequences[].gait_feature, response.sequences[].face_feature, and response.sequences[].reid_feature.
6. Compare only same-type features by dot product. Do not compare gait_feature with reid_feature or face_feature.

The response uses a sequences array because one input track can be split into
multiple clean single-person output sequences.

## Video To Sequence Workflow

Recommended when starting from local video:

1. Run examples/registered/python/local_video_to_sequence_demo/local_video_to_sequence_api_demo.py /path/to/video.mp4.
2. The demo performs local decoding, person detection, tracking, and crop export.
3. It writes one folder per detected person sequence.
4. It uploads each sequence folder to the Sequence API.
5. It saves frames and API JSON together.

Use direct POST /v1/videos only when server-side asynchronous full-video parsing is desired.
Video parsing is not the recommended entrypoint for complete per-person pose arrays.

## Video To Each Person's 2D/3D Keypoints

If the user asks for keypoints from a video, follow this path:

1. Download or use the registered Python demo.
2. Run examples/registered/python/local_video_to_sequence_demo/local_video_to_sequence_api_demo.py /path/to/video.mp4.
3. Let the demo do local detection, tracking, and crop export.
4. Upload each generated sequence folder.
5. Call POST /v1/sequences/{task_id}/gait-pose for each sequence.
6. Save result.json, pose_2d.csv, and pose_3d.csv beside the sequence frames.

Do not upload a multi-person video and expect video parse to return complete per-person 2D/3D keypoints. Video parse is for server-side asynchronous video identity parsing; gait-pose is a sequence API.

Recommended local output shape:

output/
  video_name/
    sequence_xxx/
      frame_000001.jpg
      frame_000002.jpg
      meta.txt
      result.json
      pose_2d.csv
      pose_3d.csv
    summary.csv

meta.txt should preserve crop/frame mapping from local preprocessing. If a track is split into multiple sequences by the API, save each split result as a separate output sequence.

## Sequence Input Requirements

- Use images from one tracked person sequence, ordered by time.
- Prefer person crops, not full surveillance frames with multiple people.
- Keep frames[].index in temporal order.
- Very short, static, or heavily occluded tracks may return empty sequences or validation errors.
- If one track mixes multiple people, the backend may split it into multiple clean sequences or drop ambiguous frames.
- If uploaded images are crops, keep crop_x/crop_y/crop_w/crop_h metadata locally when original-video coordinates are needed.

## Gait Pose Coordinates

- pose_2ds outer array is frames. Each frame is 3*17 floats: x0,y0,score0...x16,y16,score16.
- pose_3ds outer array is frames. Each frame is 3*17 floats: x0,y0,z0...x16,y16,z16.
- Coordinates are relative to the uploaded sequence image, not the original video frame.
- 2D origin is the uploaded image center.
- If uploaded images are crops, map back to original video coordinates using crop_x/crop_y/crop_w/crop_h from local demo metadata.
- pose_2ds[i] and pose_3ds[i] correspond to the same ordered sequence frame unless frames gives a more explicit mapping.
- Invalid frames may produce empty, null, or low-score pose entries; clients should filter by array length and score.

## Object Search Rules

- image_base64 should be raw base64 without a data:image/...;base64, prefix.
- JPEG and PNG are the safest image formats.
- Prompt can be Chinese or English when the configured upstream model supports it.
- boxes may contain zero, one, or many matches.
- No match returns boxes: [] as a successful response.
- Box coordinates are uploaded-image pixel coordinates: x1,y1 top-left and x2,y2 bottom-right.
- label is generated by the upstream model and is not a fixed taxonomy.

## Similarity Notes

- gait_feature and reid_feature are usually present for valid gait sequences.
- face_feature can be null or empty when no usable face is detected; this is not an API failure.
- Dot product same-type vectors to get similarity.
- The demo package includes examples/registered/python/sequence_similarity_demo.py, which parses folders under examples/sample_sequences and writes a pairwise CSV.

## Common Pitfalls

- 400 invalid request body on POST /v1/sequences: send JSON {"frame_count":N}; do not upload images directly to this endpoint.
- Missing object_key on /parse: pass back the object_key returned by POST /v1/sequences.
- Empty response.sequences: the uploaded frames did not form a valid moving gait sequence.
- TLS hostname mismatch: use documented public origins such as https://www.w-agent.cn/api or https://www.h-agent.ai/api, not https://api.w-agent.cn.
- 409 on video result: the async video task is still processing; poll again later.
- Do not compare raw images for identity. Use gait/face/ReID features.
- Do not read result.gait_feature at the top level. Read response.sequences[].gait_feature.
- Do not expect pose_2ds or pose_3ds from sequence parsing. Use the standalone gait-pose endpoint.
- Do not treat pose_2ds as original full-video coordinates.

## Pricing

Prices are configured in CNY minor units. USD values are estimates for budgeting before the call; the final anonymous payment amount is the x402 challenge returned by HTTP 402.
- Conversion: 1 USD = 7 CNY.
- Video parsing: ¥1.0000 (100 CNY minor units; about $0.1500) / 1K frames.
- Video result fetch: ¥0.0100 (1 CNY minor units; about $0.0100) / sequence.
- Sequence parsing: registered users pay ¥0.0100 (1 CNY minor units; about $0.0100) / output sequence; anonymous x402 calls pay ¥0.0100 (1 CNY minor units; about $0.0100) / input sequence.
- Human 2D/3D keypoints: ¥0.0100 (1 CNY minor units; about $0.0100) / sequence.
- Object Search: ¥0.1000 (10 CNY minor units; about $0.0200) / image. Trial calls consume trial quota.

## Payments

Registered users prepay with account balance.
Anonymous agents can pay per call through x402.

## Output

JSON results may include:

- gait_feature
- face_feature
- reid_feature
- reid_structure_raw
- reid_attributes
- reid_summary
- emotions
- frames and boxes
- task-scoped asset URLs
- pose_2ds and pose_3ds from the standalone gait-pose endpoint only

## Contact

support@w-agent.cn