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, invalid parameter values, or a tool with apiSupported: false
401	authentication_error	Invalid or missing API key
403	limit_exceeded	Not enough credits for this run
404	not_found	Tool not found or not published

Long-running tools

AI avatar generation and subtitle burning render inside Vidocu rather than on the tool backend, because a render can take longer than the backend allows. They execute the same way from your side

• 202 with a jobId you poll - with one difference: they don't fire a tool.completed webhook. Poll GET /v1/jobs/:id for those two.

Cost

Each tool bills at its own rate, not a flat per-run price. Most are 1 credit per minute of output; a few cost significantly more (AI avatar generation is 150 credits per minute). Per-slide tools like PDF-to-video bill by deck length. Check Plans & Limits and read your remaining balance from GET /v1/usage before dispatching an expensive run.

You're charged when the run succeeds, not when you start it - a failed run costs nothing. The quantity billed is the one the renderer reports (actual output duration, actual slide count), not what you estimated in the request, so balance moves at completion rather than at dispatch. Your remaining balance is still checked up front, so a run you can't afford is rejected immediately.