Content
# W-Agent API Examples
W-Agent provides public APIs for video parsing, tracked person sequence parsing,
identity features, ReID structured attributes, emotion output, and human 2D/3D
keypoints.
Use W-Agent when you need to:
- decide whether two tracked person sequences are the same person
- extract gait, face, and ReID identity features
- convert video into tracked person sequences
- extract 2D/3D human keypoints from each sequence
- find objects in an image from a text prompt
Websites:
```text
Global: https://www.h-agent.ai
Mainland China: https://www.w-agent.cn
```
API base URLs:
```text
Mainland China: https://www.w-agent.cn/api
Overseas entry: https://www.h-agent.ai/api
```
Use the domain closest to your region. Overseas redirects to `w-agent.cn` are
expected. Do not use `https://api.w-agent.cn` unless it is explicitly
documented.
Machine-readable API docs:
```text
Mainland China OpenAPI: https://www.w-agent.cn/api/openapi.json
Mainland China agent markdown: https://www.w-agent.cn/api/.well-known/w-agent.md
Global OpenAPI: https://www.h-agent.ai/openapi.json
Global agent markdown: https://www.h-agent.ai/.well-known/w-agent.md
Global plugin manifest: https://www.h-agent.ai/.well-known/ai-plugin.json
```
Task recipes:
```text
recipes/same-person-identity.md
recipes/video-to-2d-3d-keypoints.md
recipes/video-to-person-sequences.md
recipes/object-search.md
recipes/anonymous-x402.md
recipes/agent-mcp.md
```
MCP endpoint:
```text
Mainland China: https://www.w-agent.cn/api/mcp
Overseas entry: https://www.h-agent.ai/mcp
```
MCP config example:
```text
mcp-config.example.json
```
## Repository Contents
- `examples/registered/python`: registered-user API Key demos and MCP demo.
- `examples/registered/go`: registered-user Go demos.
- `examples/registered/cpp`: registered-user C++ demos.
- `examples/anonymous/python`: anonymous x402 payment demos.
- `examples/registered/python/local_video_to_sequence_demo`: Python local
video-to-sequence demo for registered users.
- `examples/registered/cpp/local_video_to_sequence_demo`: C++ local
video-to-sequence demo for registered users.
- `examples/registered/go/local_video_to_sequence_demo`: Go orchestration demo
that runs local preprocessing and uploads with the Go Sequence API demo.
- `examples/anonymous/python/local_video_to_sequence_demo`: Python local
video-to-sequence demo for anonymous x402 calls.
Download packages are grouped by language. Inside each language package, the
three input modes are parallel:
```text
1. Sequence input: upload an already tracked person image sequence.
2. Video input: upload a full video directly to the Video API.
3. Local video-to-sequence input: process a video locally, then upload the
extracted person sequence folders to the Sequence API.
```
## Registered User Flow
Registered-user APIs use an API Key:
```http
Authorization: Bearer <api_key>
```
Set your API Key before running demos:
```bash
export GAIT_REGISTERED_API_KEY='gak_your_api_key'
export GAIT_API_BASE_URL='https://www.w-agent.cn/api'
```
For overseas users, `GAIT_API_BASE_URL='https://www.h-agent.ai/api'` is also
supported.
## Fastest Start
Parse a local video into person sequences, upload each sequence, and call the
registered Sequence API:
```bash
pip install requests opencv-python numpy
export GAIT_REGISTERED_API_KEY='gak_your_api_key'
export GAIT_API_BASE_URL='https://www.w-agent.cn/api'
python3 examples/registered/python/local_video_to_sequence_demo/local_video_to_sequence_api_demo.py /path/to/video.mp4
```
If you already have tracked person crop folders and only want identity
similarities:
```bash
pip install requests
export GAIT_REGISTERED_API_KEY='gak_your_api_key'
export GAIT_API_BASE_URL='https://www.w-agent.cn/api'
python3 examples/registered/python/sequence_similarity_demo.py examples/sample_sequences
```
### Python
```bash
pip install requests
python3 examples/registered/python/sequence_and_video_api_demo.py
```
MCP demo:
```bash
python3 examples/registered/python/mcp_api_demo.py
```
### Local Video-To-Sequence Input
Users can either upload full videos directly to W-Agent, or process videos
locally first and upload the extracted person sequences. Each language package
has its own local video-to-sequence entry:
```bash
python3 examples/registered/python/local_video_to_sequence_demo/local_video_to_sequence_api_demo.py /path/to/video.mp4
./examples/registered/cpp/local_video_to_sequence_demo/run_local_video_to_sequence_api_demo.sh /path/to/video.mp4
./examples/registered/go/local_video_to_sequence_demo/run_local_video_to_sequence_api_demo.sh /path/to/video.mp4
python3 examples/anonymous/python/local_video_to_sequence_demo/local_video_to_sequence_x402_demo.py /path/to/video.mp4
```
Each local demo writes one folder per detected person sequence and then uploads
the generated sequence folders.
### Go
```bash
cd examples/registered/go/sequence_demo
./build.sh
./registered_sequence_demo
```
```bash
cd examples/registered/go/video_demo
./build.sh
./registered_video_demo
```
### C++
The C++ demos require `libcurl` and `nlohmann/json`.
Ubuntu:
```bash
sudo apt-get install -y libcurl4-openssl-dev nlohmann-json3-dev
```
Build and run:
```bash
cd examples/registered/cpp/sequence_demo
./build.sh
./build/registered_sequence_demo
```
```bash
cd examples/registered/cpp/video_demo
./build.sh
./build/registered_video_demo
```
## Anonymous x402 Flow
Anonymous public APIs do not use an API Key. The server returns HTTP 402, the
client signs an x402 payment payload with an EVM wallet, and then retries the
same request with payment headers.
Install dependencies:
```bash
pip install requests eth-account 'x402[evm]' web3
```
Set a test wallet private key before running:
```bash
export GAIT_TEST_WALLET_PRIVATE_KEY='0x...'
export GAIT_API_BASE_URL='https://www.w-agent.cn/api'
```
Run:
```bash
python3 examples/anonymous/python/anonymous_sequence_x402_demo.py
python3 examples/anonymous/python/anonymous_sequence_and_video_x402_demo.py
```
## Notes
- Do not commit real API Keys or wallet private keys.
- Sequence demos expect a local directory of ordered person crop images.
- Video demos expect a local video file path.
- Upload URLs returned by the API are service-relative paths and are resolved
against `GAIT_API_BASE_URL`.
## Contact
Email: support@w-agent.cn
