API Reference

Sandcut keeps the public API deliberately small.

Authentication

All processing requests require a bearer token.

Authorization: Bearer <token>

Endpoints

Endpoint	Method	Purpose
/health	GET	Basic health response
/doc	GET	Human-readable metadata
/openapi.json	GET	Tooling-friendly schema
/video/process	POST	Media processing entrypoint

POST /video/process

Request body

{
  "input_url": "https://example.com/video.mp4",
  "ffmpeg_args": ["-vf", "scale=640:360", "-c:v", "libx264", "-c:a", "aac"],
  "seek": {
    "mode": "hybrid",
    "start": 30,
    "duration": 8
  }
}

Multiple input files

Use inputs when FFmpeg needs more than one remote file source.

{
  "inputs": [
    "https://example.com/intro.mp4",
    "https://example.com/main.mp4"
  ],
  "ffmpeg_args": [
    "-filter_complex",
    "[0:v][1:v]concat=n=2:v=1:a=0[v]",
    "-map",
    "[v]"
  ]
}

Use either input_url or inputs, not both.

seek object

Field	Type	Required	Notes
mode	string	no	fast, accurate, or hybrid; defaults to accurate
start	number	yes	non-negative start time in seconds
duration	number	no	clip length in seconds
end	number	no	alternative to duration; must be greater than start

Use either duration or end, not both.

Success response

{
  "success": true,
  "outputUrl": "https://cdn.example.com/output/20260313/uuid.mp4",
  "size": 395768,
  "sizeKnown": true,
  "input": {
    "size": 8212301,
    "sizeKnown": true,
    "probeMethod": "HEAD"
  },
  "seek": {
    "mode": "hybrid",
    "startSeconds": 30,
    "durationSeconds": 8
  },
  "timing": {
    "total": 4972,
    "container": 3819,
    "upload": 771
  }
}

For multi-input requests, the response also includes an inputs array with per-input probe metadata.

Error envelope

{
  "error": {
    "code": 3003,
    "message": "Video size exceeds limit",
    "details": "Input is 300000000 bytes, limit is 209715200 bytes"
  }
}

Validation rules

• input_url must be http or https
• inputs can contain 1 to 8 remote input URLs
• private IPs, localhost, and internal metadata domains are rejected
• ffmpeg_args cannot include nested input flags such as -i
• raw seek overrides such as -ss and -to are rejected from ffmpeg_args
• dangerous protocol prefixes such as pipe: and file: are rejected
• global seek is only supported for single-input requests

Schema

Use the static schema in /openapi.json for client generation or API catalog tooling.