API docs

With the API, your own scripts, bots or tools like n8n can submit clips, check their status and download finished clips. Everything the API does also works in the app, and each clip costs the same tokens.

Who can use the API

The API is in testing right now and only enabled for selected testers. Without access it answers with not_available.

From the Premium plan and while you have token pack balance. This is checked on every request: if you move to a smaller plan without pack balance, the API answers with plan_required until one of the conditions is met again.

Key

You create your key in the settings under "API access". It is shown exactly once, after that we only keep a one-way hash. A new key immediately invalidates the old one.

Authentication

Send the key in the header with every request. All URLs start with https://lazyclipper.com/api/v1.

Authorization: Bearer ct_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

Submit a clip

Send JSON. Only url is required. Values your plan does not include or that are unknown fall back to the default, just like in the app.

The response comes with status 202 as soon as the clip is in the queue:

{
  "id": "590ad858-8e71-4fac-ac88-d86fbf4cc7c5",
  "status": "queued",
  "queuePosition": 2,
  "tokensCharged": 10,
  "tokensRemaining": 2490,
  "statusUrl": "/api/v1/clips/590ad858-8e71-4fac-ac88-d86fbf4cc7c5"
}

Example: the full flow

# 1. Submit a clip
curl -X POST https://lazyclipper.com/api/v1/clips \
  -H "Authorization: Bearer $LAZYCLIPPER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-clip-001" \
  -d '{"url":"https://www.twitch.tv/channel/clip/ClipSlug","targetDuration":"30"}'

# 2. Poll the status until it is "done" or "failed" (at most every 5 seconds)
curl https://lazyclipper.com/api/v1/clips/CLIP_ID \
  -H "Authorization: Bearer $LAZYCLIPPER_KEY"

# 3. Download the finished clip
curl -L -o clip.mp4 https://lazyclipper.com/api/v1/clips/CLIP_ID/file \
  -H "Authorization: Bearer $LAZYCLIPPER_KEY"

Status

Avoiding duplicate orders

Send your own POST /clips with Idempotency-Key , for example an ID from your system. If the same request arrives again within 24 hours, say because your script retries after a network error, you get the first response back and nothing is charged twice. The response then carries the header Idempotent-Replayed: true.

Limits

• 120 requests per minute per account
• 30 new clips per 10 minutes per account
• If the queue is full you get queue_full. Wait for the seconds given in the Retry-After header.
• Higher plans go first in the queue, and waiting clips move up automatically over time.

Errors

Errors always have the same shape:

{ "error": { "code": "insufficient_tokens", "message": "Not enough tokens (10 needed, 0 left). ..." } }

Versions

Version 1 stays stable. New fields may be added, existing ones keep their meaning. Anything that would break existing scripts only comes as a new version with advance notice.

Using the API is also subject to the Terms of Service, especially §5d.