{"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"API Key","description":"Registered users pass Authorization: Bearer \u003capi_key\u003e.","scheme":"bearer","type":"http"}}},"info":{"description":"W-Agent public APIs for person identity recognition, emotion recognition, video parsing, gait sequence parsing, human 2D/3D keypoints, and Object Search.\n\nBase URL:\n- Mainland China: https://www.w-agent.cn/api\n- Overseas entry: https://www.h-agent.ai/api. Redirects to w-agent.cn are expected.\n- Do not guess https://api.w-agent.cn unless it is explicitly documented.\n\nTask selection:\n- Same person or not: upload one tracked person sequence, call /v1/sequences/{task_id}/parse, then dot-product same-type gait_feature, face_feature, or reid_feature.\n- Video to identity features: use /v1/videos for server-side asynchronous parsing, or run the local video-to-sequence demo first if local sequence folders and JSON files are needed.\n- Video to each person's 2D/3D keypoints: run local video-to-sequence preprocessing, upload each generated sequence, then call /v1/sequences/{task_id}/gait-pose for each sequence.\n- Existing single-person sequence to keypoints: upload sequence frames, then call /v1/sequences/{task_id}/gait-pose.\n- Image text search: call /v1/object-search with raw image_base64 and prompt.\n\nImportant boundaries:\n- Video parsing mainly returns person sequences, boxes, identity features, attributes, and emotions. It is not the complete per-person pose endpoint.\n- pose_2ds and pose_3ds are relative to uploaded sequence images, not original full video frames. If uploaded images are crops, use local crop metadata to map back to the original video.\n- Object Search boxes are original-image pixel coordinates. No match returns boxes: [] and is not an error.\n- Registered users use Authorization: Bearer \u003capi_key\u003e. Anonymous agents use public routes and x402 HTTP 402 payment_context flow.\n\nAgent discovery:\n- Agent guide: https://www.w-agent.cn/api/.well-known/w-agent.md\n- OpenAPI: https://www.w-agent.cn/api/openapi.json\n- GitHub examples: https://github.com/w-agent-ai/api-example\n- Task recipes: https://github.com/w-agent-ai/api-example/tree/main/recipes\n- MCP config example: https://github.com/w-agent-ai/api-example/blob/main/mcp-config.example.json\n- MCP endpoint: https://www.w-agent.cn/api/mcp","title":"W-Agent API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/mcp":{"post":{"description":"MCP Streamable HTTP JSON-RPC endpoint. Supports initialize, tools/list, and tools/call.","operationId":"mcpJsonRPC","requestBody":{"content":{"application/json":{"schema":{"properties":{"id":{},"jsonrpc":{"example":"2.0","type":"string"},"method":{"example":"tools/list","type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"MCP Streamable HTTP JSON-RPC endpoint. Supports initialize, tools/list, and tools/call.","tags":["Agent"]}},"/v1/object-search":{"post":{"description":"Find targets in one uploaded image from a text prompt. image_base64 should be raw base64 without a data:image/...;base64, prefix. JPEG and PNG are safest. boxes are original-image pixel coordinates: x1,y1 top-left and x2,y2 bottom-right. No match returns boxes: [] as a successful response. label is model-generated, not a fixed taxonomy.","operationId":"objectSearch","requestBody":{"content":{"application/json":{"schema":{"properties":{"image_base64":{"type":"string"},"prompt":{"type":"string"}},"required":["image_base64","prompt"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Find targets in one image from a text prompt.","tags":["Object Search"]}},"/v1/payment-capabilities":{"get":{"description":"List supported payment capabilities including x402 routes.","operationId":"getPaymentCapabilities","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"List supported payment capabilities including x402 routes.","tags":["Discovery"]}},"/v1/public/object-search/trial":{"post":{"description":"No-registration trial Object Search call.","operationId":"trialObjectSearch","requestBody":{"content":{"application/json":{"schema":{"properties":{"fingerprint":{"type":"string"},"image_base64":{"type":"string"},"prompt":{"type":"string"}},"required":["image_base64","prompt"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"No-registration trial Object Search call.","tags":["Trial"]}},"/v1/public/sequences":{"post":{"description":"Create an anonymous public sequence parsing task. Upload each frame to uploads[].upload_url and keep uploads[].object_key for parse.","operationId":"createPublicSequenceTask","requestBody":{"content":{"application/json":{"schema":{"properties":{"frame_count":{"minimum":1,"type":"integer"}},"required":["frame_count"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Create an anonymous public sequence parsing task. Upload each frame to uploads[].upload_url and keep uploads[].object_key for parse.","tags":["Anonymous Sequences"]}},"/v1/public/sequences/{task_id}":{"delete":{"description":"Mark an anonymous public sequence task for early cleanup.","operationId":"deletePublicSequenceTask","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Mark an anonymous public sequence task for early cleanup.","tags":["Anonymous Sequences"]},"get":{"description":"Get anonymous public sequence task status.","operationId":"getPublicSequenceStatus","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Get anonymous public sequence task status.","tags":["Anonymous Sequences"]}},"/v1/public/sequences/{task_id}/gait-pose":{"post":{"description":"Run anonymous standalone human 2D/3D keypoint extraction. The request must pass frames[].object_key returned by createPublicSequenceTask.","operationId":"getPublicSequenceHumanKeypoints","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"frame_count":{"minimum":1,"type":"integer"},"frames":{"items":{"properties":{"index":{"minimum":0,"type":"integer"},"object_key":{"type":"string"}},"required":["index","object_key"],"type":"object"},"type":"array"}},"required":["frames"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Run anonymous standalone human 2D/3D keypoint extraction. The request must pass frames[].object_key returned by createPublicSequenceTask.","tags":["Anonymous Sequences"]}},"/v1/public/sequences/{task_id}/parse":{"post":{"description":"Parse an anonymous public sequence. The request must pass frames[].object_key returned by createPublicSequenceTask.","operationId":"parsePublicSequence","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"frame_count":{"minimum":1,"type":"integer"},"frames":{"items":{"properties":{"index":{"minimum":0,"type":"integer"},"object_key":{"type":"string"}},"required":["index","object_key"],"type":"object"},"type":"array"}},"required":["frames"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Parse an anonymous public sequence. The request must pass frames[].object_key returned by createPublicSequenceTask.","tags":["Anonymous Sequences"]}},"/v1/public/sequences/{task_id}/result":{"get":{"description":"Fetch the stored anonymous sequence parse response.","operationId":"getPublicSequenceResult","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Fetch the stored anonymous sequence parse response.","tags":["Anonymous Sequences"]}},"/v1/public/sequences/{task_id}/settle":{"post":{"description":"Settle or request the anonymous sequence parse or gait-pose payment challenge.","operationId":"settlePublicSequence","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"settlement_ref":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Settle or request the anonymous sequence parse or gait-pose payment challenge.","tags":["Anonymous Sequences"]}},"/v1/public/videos":{"post":{"description":"Create an anonymous public video parsing task. Upload the binary to the returned upload_url.","operationId":"createPublicVideoTask","requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"minimum":0,"type":"integer"}},"required":["filename"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Create an anonymous public video parsing task. Upload the binary to the returned upload_url.","tags":["Anonymous Videos"]}},"/v1/public/videos/{task_id}":{"delete":{"description":"Mark an anonymous public video task for early cleanup.","operationId":"deletePublicVideoTask","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Mark an anonymous public video task for early cleanup.","tags":["Anonymous Videos"]},"get":{"description":"Get anonymous public video task status.","operationId":"getPublicVideoStatus","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Get anonymous public video task status.","tags":["Anonymous Videos"]}},"/v1/public/videos/{task_id}/result":{"get":{"description":"Fetch anonymous public video result. May return HTTP 402 until phase 2 is paid.","operationId":"getPublicVideoResult","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Fetch anonymous public video result. May return HTTP 402 until phase 2 is paid.","tags":["Anonymous Videos"]}},"/v1/public/videos/{task_id}/settle-phase1":{"post":{"description":"Settle or request the phase 1 video parsing payment challenge.","operationId":"settlePublicVideoPhase1","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"settlement_ref":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Settle or request the phase 1 video parsing payment challenge.","tags":["Anonymous Videos"]}},"/v1/public/videos/{task_id}/settle-phase2":{"post":{"description":"Settle or request the phase 2 video result payment challenge.","operationId":"settlePublicVideoPhase2","parameters":[{"description":"Task token returned by the anonymous public create endpoint.","in":"header","name":"X-Task-Token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"settlement_ref":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Settle or request the phase 2 video result payment challenge.","tags":["Anonymous Videos"]}},"/v1/sequences":{"post":{"description":"Create upload targets for one ordered tracked-person image sequence. Send only frame_count here; upload images to uploads[].upload_url, then pass uploads[].object_key back to /parse or /gait-pose.","operationId":"createSequenceTask","requestBody":{"content":{"application/json":{"schema":{"properties":{"frame_count":{"minimum":1,"type":"integer"}},"required":["frame_count"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Create a gait sequence parsing task.","tags":["Sequences"]}},"/v1/sequences/{task_id}/gait-pose":{"post":{"description":"Use for 2D/3D keypoints from an uploaded sequence. pose_2ds[i] and pose_3ds[i] correspond to the same ordered sequence frame unless frames provides a more explicit mapping. Coordinates are relative to the uploaded sequence image; if the input is a crop, map back to original video coordinates with local crop metadata such as crop_x and crop_y.","operationId":"getSequenceHumanKeypoints","requestBody":{"content":{"application/json":{"schema":{"properties":{"frame_count":{"minimum":1,"type":"integer"},"frames":{"items":{"properties":{"index":{"minimum":0,"type":"integer"},"object_key":{"type":"string"}},"required":["index","object_key"],"type":"object"},"type":"array"}},"required":["frames"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Run standalone human 2D/3D keypoint extraction for an uploaded sequence. pose_2ds and pose_3ds coordinates are relative to the uploaded sequence images, not the original full video frame. The request must pass frames[].object_key returned by createSequenceTask.","tags":["Sequences"]}},"/v1/sequences/{task_id}/parse":{"post":{"description":"Use for identity features and attributes from an already detected/tracked person sequence. Input should be one ordered track, preferably person crops. The response is sequences[] because ReID may split one mixed track into multiple clean single-person outputs. Compare only same-type gait_feature, face_feature, or reid_feature by dot product. Do not expect pose_2ds or pose_3ds here; use /gait-pose for keypoints.","operationId":"parseSequence","requestBody":{"content":{"application/json":{"schema":{"properties":{"frame_count":{"minimum":1,"type":"integer"},"frames":{"items":{"properties":{"index":{"minimum":0,"type":"integer"},"object_key":{"type":"string"}},"required":["index","object_key"],"type":"object"},"type":"array"}},"required":["frames"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Parse an uploaded tracked person sequence and return sequences[] with gait/face/ReID identity features, attributes, and emotion outputs. A single input track may split into multiple output sequences when ReID detects an ID switch. The request must pass frames[].object_key returned by createSequenceTask.","tags":["Sequences"]}},"/v1/sequences/{task_id}/result":{"get":{"description":"Fetch the stored gait sequence parsing response with all split sequence results.","operationId":"getSequenceResult","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Fetch the stored gait sequence parsing response with all split sequence results.","tags":["Sequences"]}},"/v1/uploads/{task_id}/{index}":{"put":{"description":"Upload the binary image body for one frame to the upload_url returned by createSequenceTask. Keep the matching object_key for later parse or gait-pose calls.","operationId":"uploadSequenceFrame","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Upload one sequence image frame.","tags":["Sequences"]}},"/v1/video-uploads/{task_id}":{"put":{"description":"Upload the video binary using the upload token returned by createVideoTask.","operationId":"uploadVideo","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[],"summary":"Upload the video binary using the upload token returned by createVideoTask.","tags":["Videos"]}},"/v1/videos":{"post":{"description":"Create an asynchronous server-side video parsing task. Video parsing is for person sequences, boxes, identity features, attributes, and emotions. If the goal is every person's complete 2D/3D keypoints, run local video-to-sequence preprocessing first and call /v1/sequences/{task_id}/gait-pose per generated sequence.","operationId":"createVideoTask","requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"type":"string"},"filename":{"type":"string"},"size_bytes":{"minimum":0,"type":"integer"}},"required":["filename"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Create a video parsing task.","tags":["Videos"]}},"/v1/videos/{task_id}":{"get":{"description":"Get video task status.","operationId":"getVideoStatus","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Get video task status.","tags":["Videos"]}},"/v1/videos/{task_id}/complete":{"post":{"description":"Mark video upload complete and allow asynchronous processing.","operationId":"completeVideoUpload","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Mark video upload complete and allow asynchronous processing.","tags":["Videos"]}},"/v1/videos/{task_id}/result":{"get":{"description":"Fetch asynchronous video parsing results after status succeeds. Results contain person sequences, frame boxes, identity features, attributes, and emotions. Do not use this as the complete per-person pose endpoint; for pose_2ds and pose_3ds, use sequence gait-pose.","operationId":"getVideoResult","responses":{"200":{"description":"Success"},"400":{"description":"Invalid request"},"402":{"description":"Payment required for anonymous paid flows"},"409":{"description":"Task is not ready or payment is required"}},"security":[{"bearerAuth":[]}],"summary":"Fetch parsed video results after processing succeeds.","tags":["Videos"]}}},"security":[{"bearerAuth":[]}],"servers":[{"description":"Mainland China","url":"https://www.w-agent.cn/api"},{"description":"Overseas entry","url":"https://www.h-agent.ai/api"},{"description":"Current request origin","url":"https://www.w-agent.cn/api"}],"x-w-agent":{"agent_markdown_url":"https://www.w-agent.cn/api/.well-known/w-agent.md","anonymous_payment":"Public endpoints may return HTTP 402 with x402 payment_context. Anonymous x402 payment is handled by public HTTP APIs, not by MCP JSON-RPC tools.","examples_url":"https://github.com/w-agent-ai/api-example","mcp_config_url":"https://github.com/w-agent-ai/api-example/blob/main/mcp-config.example.json","mcp_url":"https://www.w-agent.cn/api/mcp","pricing":{"anonymous_settlement_currency":"USD","cny_usd_exchange_rate":"7","currency":"CNY","estimated":{"gait_pose_per_sequence":{"cny_minor":1,"estimated_cny":0.01,"estimated_usd":0.01,"estimated_usd_minor":1,"estimated_usd_text":"$0.01"},"object_search_price_per_image":{"cny_minor":10,"estimated_cny":0.1,"estimated_usd":0.02,"estimated_usd_minor":2,"estimated_usd_text":"$0.02"},"sequence_per_k_frames":{"cny_minor":0,"estimated_cny":0,"estimated_usd":0,"estimated_usd_minor":0,"estimated_usd_text":"$0.00"},"sequence_per_sequence":{"cny_minor":1,"estimated_cny":0.01,"estimated_usd":0.01,"estimated_usd_minor":1,"estimated_usd_text":"$0.01"},"video_per_k_frames":{"cny_minor":100,"estimated_cny":1,"estimated_usd":0.15,"estimated_usd_minor":15,"estimated_usd_text":"$0.15"}},"eurc_usd_exchange_rate":"1.15","gait_pose_per_k_frames":100,"gait_pose_per_sequence":1,"object_search_price_per_image":10,"sequence_per_k_frames":0,"sequence_per_sequence":1,"video_per_k_frames":100},"recipes_url":"https://github.com/w-agent-ai/api-example/tree/main/recipes","similarity":"Use dot product between same-type gait_feature, face_feature, and reid_feature vectors."}}