Quickstart

Extract a clip in three API calls.

---

Base URL

https://api.ottocut.com

All responses use the envelope:

{ "data": { ... }, "error": null, "meta": { "request_id": "..." } }

---

Path A — Upload a file

1. Request an upload URL

curl -X POST https://api.ottocut.com/media/upload-url

{
  "data": {
    "media_id": "med_abc123",
    "signed_upload_url": "https://storage.googleapis.com/...",
    "expires_at": "2026-05-09T14:00:00Z"
  }
}

2. Upload the file directly to storage

curl -X PUT "<signed_upload_url>" \
  -H "Content-Type: video/mp4" \
  --data-binary @my-video.mp4

3. Finalize

curl -X POST https://api.ottocut.com/media/med_abc123/finalize

{ "data": { "media_id": "med_abc123", "status": "extracting_audio" } }

---

Path B — Ingest from a URL

curl -X POST https://api.ottocut.com/media \
  -H "Content-Type: application/json" \
  -d '{ "source_url": "https://example.com/media/interview.mp4" }'

{ "data": { "media_id": "med_xyz789", "status": "downloading" } }

---

Poll until ready

curl https://api.ottocut.com/media/med_abc123

{
  "data": {
    "media_id": "med_abc123",
    "status": "ready",
    "duration_sec": 312.4,
    "transcript": [
      { "word": "hello", "start": 1.2, "end": 1.6 },
      ...
    ]
  }
}

status progression: pending_upload → extracting_audio → transcribing → ready (or failed).

Poll every 5–10 seconds. transcript is included once status is ready.

---

Create a clip

curl -X POST https://api.ottocut.com/clips \
  -H "Content-Type: application/json" \
  -d '{
    "media_id": "med_abc123",
    "start": { "type": "phrase", "value": "welcome to the show" },
    "end":   { "type": "phrase", "value": "thanks for watching" }
  }'

{
  "data": {
    "clip_id": "clp_def456",
    "status": "ready",
    "download_url": "https://storage.googleapis.com/...",
    "expires_at": "2026-05-09T15:00:00Z",
    "start_sec": 4.1,
    "end_sec": 298.7
  }
}

The download_url is a signed URL valid for 1 hour. See Clipping Reference for marker options.

---

Retrieve a clip later

curl https://api.ottocut.com/clips/clp_def456

Returns the same shape as above with a freshly signed download_url.