Long video.
Short request.

Authentication

Send your personal key in the Api-Key header. The backend resolves its owner; never send a Firebase token or user ID. Keys inherit the owner’s plan and Split Video limits.

Api-Key: ib_live_••••••••••••••••

Upload once. Queue once.

Upload a video as multipart form data. With split=true, IMABIRD immediately queues the same pipeline used by Cuts. Set it to false to upload without creating cuts. The video must be at least 3 minutes long.

curl --request POST \
  --url https://www.imabird.productions/api/v1/videos \
  --header "Api-Key: $IMABIRD_API_KEY" \
  --header "Idempotency-Key: upload-episode-42" \
  --form "file=@podcast-episode.mp4" \
  --form "name=Podcast highlights"

Cut preset

Cuts use your active Cut preset, as in the web app: clip length, aspect ratio, reframing, caption style and video text. Send cutPresetId to use another saved preset. These fields override the preset for one request: minClipDurationSeconds, maxClipDurationSeconds, previewAspectRatioKey, reframingPreset, followSubject, autoGenerateVideoText, removeFillersAndPauses, highlightKeywords.

previewAspectRatioKey accepts 9:16, 1:1, or 16:9. Valid reframingPreset values come from GET /api/reframer/presets.

Safe retries

Idempotency-Key is required. Repeating the same request and key returns the original operation without uploading or queueing twice. Reusing it with different parameters returns 409.

Response · 202

{
  "operationId": "01f0e7…",
  "status": "queued",
  "video": {
    "filename": "podcast-episode_a1b2c3.mp4",
    "size": 284991032,
    "uploadJobId": "8f01…"
  },
  "settings": {
    "cutPresetId": "default",
    "minClipDurationSeconds": 30,
    "maxClipDurationSeconds": 60,
    "previewAspectRatioKey": "9:16",
    "reframingPreset": "intelligent",
    "captions": {
      "fontFamily": "Anton",
      "fontSize": 35,
      "textColor": "#FFFF00",
      "outlineColor": "#000000",
      "outlineWidth": 4,
      "animation": "reveal-pop-word"
    },
    "autoGenerateVideoText": true,
    "removeFillersAndPauses": false,
    "highlightKeywords": false
  },
  "split": {
    "jobId": "d1c9…",
    "status": "queued"
  }
}

settings lists the options the request used.

Check status

Poll the public operation—not the internal job API. Cuts are reframed after the split, so status is completed only once reframing is completed. Completed operations return only public project and cut identifiers.

curl https://www.imabird.productions/api/v1/operations/$OPERATION_ID \
  --header "Api-Key: $IMABIRD_API_KEY"

{
  "operationId": "01f0e7…",
  "status": "completed",
  "reframing": "completed",
  "completedAt": "2026-10-07T13:27:32+00:00",
  "split": {
    "jobId": "d1c9…",
    "status": "completed",
    "progress": 1,
    "result": {
      "releaseId": "project-1791…",
      "cutIds": ["project-1791…-ca0d", "project-1791…-070b"]
    }
  }
}

Export a cut

Render one cut from cutIds to MP4. resolution is the short side: 360p, 480p, 720p, or 1080p (default). Idempotency-Key is required. A cut that is still being reframed returns 409.

curl --request POST \
  --url https://www.imabird.productions/api/v1/cuts/$CUT_ID/exports \
  --header "Api-Key: $IMABIRD_API_KEY" \
  --header "Idempotency-Key: export-episode-42-cut-1" \
  --header "Content-Type: application/json" \
  --data '{"resolution": "1080p"}'

Download

Poll the export from the Location header. When status is completed, download.url serves the MP4 for 15 minutes. Do not send your API key to it. Read the export again for a new link.

{
  "exportId": "5b2e…",
  "cutId": "project-1791…-ca0d",
  "resolution": "1080p",
  "status": "completed",
  "progress": 1,
  "download": {
    "url": "https://storage.googleapis.com/…",
    "expiresAt": "2026-10-07T14:00:00+00:00",
    "filename": "podcast-highlights_9f2c1a.mp4",
    "sizeBytes": 18350112,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 41.5
  }
}

Errors

400 missing idempotency key, or a video shorter than 3 minutes · 401 invalid API key · 403 missing scope, plan access, or account limit reached · 404 cut or export not found · 409 idempotency conflict, or the cut is still being reframed · 413 storage limit exceeded · 415 file is not a video · 422 invalid option or unknown cutPresetId · 429 rate limited.