Execute Tool

POST /v1/tools/:type/execute

Start an asynchronous tool execution job. The request body is dynamic and depends on the tool's parameter schema — use List Tools or Get Tool to discover required inputs.

Path parameters

Parameter	Type	Required	Description
type	string	Yes	Tool type identifier (e.g. video-trimmer)

Request body

The body is a JSON object whose keys match the tool's parameters[].name fields. File inputs must be provided as public HTTP(S) URLs.

Examples

Trim a video

curl -X POST https://api.vidocu.ai/v1/tools/video-trimmer/execute \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/my-video.mp4",
    "startTime": 10,
    "endTime": 60
  }'

Extract a transcript

curl -X POST https://api.vidocu.ai/v1/tools/video-transcript-extractor/execute \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/my-video.mp4",
    "language": "en"
  }'

Response 202 Accepted

{
  "jobId": "tool_1708300000000_abc1234",
  "status": "pending",
  "tool": "video-trimmer"
}

Polling for completion

Use the Jobs endpoint to check progress:

curl https://api.vidocu.ai/v1/jobs/tool_1708300000000_abc1234 \
  -H "Authorization: Bearer vdo_live_your_key_here"

Or listen for the tool.completed or tool.failed webhook events.

Errors

Status	Code	Cause
400	validation_error	Missing required fields or invalid parameter values
401	authentication_error	Invalid or missing API key
404	not_found	Tool not found or not published