Tool Jobs API

The Tool Jobs API lets you queue common video edits through POST /v1/tools/{toolId}/jobs, poll for completion, and download the result. It is the server-side equivalent of the browser tools at https://ilovevideoeditor.com/tools/{toolId}.

Base URLs

Environment	URL
Production	https://api.ilovevideoeditor.com

Authentication

Tool jobs accept the same authentication as the rest of the API:

• API key — x-api-key: YOUR_API_KEY
• Bearer token — Authorization: Bearer <jwt>

API keys are created in the dashboard under Account > API Keys. Bearer tokens are used by the dashboard and authenticated studio routes.

Queue a tool job

curl -X POST https://api.ilovevideoeditor.com/v1/tools/trim-video/jobs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "inputUrl": "https://cdn.example.com/video.mp4",
    "config": {
      "startTime": 2,
      "endTime": 8
    },
    "webhookUrl": "https://your-app.com/webhooks/ilovevideoeditor"
  }'

Request body

Field	Type	Required	Description
inputUrl	string (URL)	yes	Public URL of the source video. blob: and file: URLs are rejected.
config	object	yes	Tool-specific configuration. Each tool accepts a different set of fields; see the Full OpenAPI Reference for schemas.
webhookUrl	string (URL)	no	URL called when the job completes or fails.
duration	number	no	Source duration in seconds. When omitted, the server probes the source.
dimensions	{ width, height }	no	Source display dimensions. When omitted, the server probes the source.

Response

{
  "jobId": "018f...",
  "status": "processing",
  "stage": "processing",
  "mode": "native"
}

Field	Description
jobId	UUID of the queued job. Use it for polling and download.
status	processing, rendering, completed, failed, etc.
stage	Human-readable stage mapped from the pipeline status.
mode	native for simple ffmpeg/MediaBunny jobs, render for full VideoJSON rendering.

Poll for status

curl https://api.ilovevideoeditor.com/v1/tools/jobs/018f... \
  -H "x-api-key: YOUR_API_KEY"

Response while processing:

{
  "jobId": "018f...",
  "status": "rendering",
  "stage": "rendering",
  "mode": "render",
  "progress": {
    "done": 12,
    "total": 30,
    "percent": 40
  }
}

Response when completed:

{
  "jobId": "018f...",
  "status": "completed",
  "stage": "completed",
  "mode": "native",
  "progress": {
    "done": 1,
    "total": 1,
    "percent": 100
  },
  "url": "https://cdn.ilovevideoeditor.com/tools/018f.../output.mp4",
  "outputs": [
    {
      "provider": "r2",
      "outputKey": "tools/018f.../output.mp4",
      "outputUrl": "https://cdn.ilovevideoeditor.com/tools/018f.../output.mp4",
      "outputSizeBytes": 1234567
    }
  ]
}

Field	Description
status / stage	Current job state.
mode	native or render.
progress	Optional render progress with done, total, and percent.
url	Signed download URL when status is completed.
outputs	Array of output destinations with size information.
error	Error message when status is failed.

Download the result

curl -L https://api.ilovevideoeditor.com/v1/tools/jobs/018f.../download \
  -H "x-api-key: YOUR_API_KEY" \
  -o output.mp4

The endpoint returns a 302 redirect to a signed download URL. The download is metered against your workspace bandwidth.

Webhooks

If you provide webhookUrl when queueing, the server sends a POST request there when the job finishes:

{
  "id": "018f...",
  "status": "completed",
  "progress": 100,
  "url": "https://cdn.ilovevideoeditor.com/tools/018f.../output.mp4",
  "error": null,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "completedAt": "2025-01-01T00:00:12.000Z"
}

Possible status values in the webhook are pending, rendering, completed, and failed. Treat the webhook as a notification and always verify the job state with GET /v1/tools/jobs/{id} if the request is untrusted.

Tool modes and pricing

• Native (mode: "native") — simple tools run directly through ffmpeg/MediaBunny. Cost is a flat 0.01 credits per job.
• Render (mode: "render") — studio tools compile to a full VideoJSON scene. Cost is calculated with the standard render cost formula based on duration, resolution, and framerate.

The server chooses the mode automatically. For example, add-border uses the native path for square corners but switches to the render path when borderRadius > 0.

Error handling

Status	Meaning	What to do
400	Invalid request body or unsupported local URL.	Check the details field and the tool config shape.
402	Insufficient credits.	Purchase credits or reduce job complexity.
404	Tool not found or job not accessible.	Verify the toolId and job ownership.
429	Too many active jobs.	Wait for an existing job to finish before queueing another.
502	Worker or render pipeline submission failed.	Retry with exponential backoff; contact support if it persists.

Example: crop a video

curl -X POST https://api.ilovevideoeditor.com/v1/tools/crop-video/jobs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "inputUrl": "https://cdn.example.com/video.mp4",
    "config": {
      "cropTop": 0.1,
      "cropBottom": 0.1,
      "cropLeft": 0,
      "cropRight": 0
    }
  }'

Example: add text overlay

curl -X POST https://api.ilovevideoeditor.com/v1/tools/add-text/jobs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "inputUrl": "https://cdn.example.com/video.mp4",
    "config": {
      "text": "Hello world",
      "fontSize": 64,
      "color": "#ffffff",
      "positionX": 0.5,
      "positionY": 0.9
    }
  }'

See also

• Studio — browser-based visual editor for the same edits.
• REST API Quick Reference — general API authentication and render endpoints.
• Full OpenAPI Reference — full machine-readable spec.