songs2vid/website/docs/api/overview.md

sidebar_position

sidebar_position
1

API overview

Programmatic uploads and batch jobs for self-hosted Songs2VID. Generate your API key under Dashboard → Settings → API access.

Keys start with s2yt_live_ and are shown once at creation.

Authentication

Send the key on every request:

Authorization: Bearer s2yt_live_your_key_here

Requirements:

• S2VID_EDITION=selfhosted (Compose sets this by default)
• YouTube channel connected (sign in with Google OAuth that includes YouTube scopes)

OAuth setup: Getting started and Google’s OAuth 2.0 for Web Server Applications. YouTube scopes/API: YouTube Data API Overview.

Rate limits

Self-hosted editions use a very high per-account ceiling (effectively unlimited for normal automation). You will rarely see 429.

If a limit is hit, the response is 429 with retryAfterSeconds and a Retry-After header. See Endpoints — HTTP errors.

Choosing a flow

Recommended: two-step (especially 5+ audio files)

1. Upload each file with POST /api/v1/upload
2. Create the job with POST /api/v1/jobs (JSON paths)

This avoids huge multipart bodies. Self-hosted max batch size is 100 tracks per job.

One-shot batch: small packs only

POST /api/v1/jobs/batch accepts one cover image and a few audio files in a single multipart request. Large bodies often fail with:

failed to parse body as FormData

Prefer two-step for albums or long tracklists.

Multipart tips

• Do not set Content-Type manually for multipart; the client must include the boundary
• In Postman: Body → form-data; each audio field key must be exactly audio (type File)
• If a file field shows a warning, re-select the file from disk

Job lifecycle

1. Create job → status PENDING
2. Worker picks items → ENCODING → UPLOADING → COMPLETED or FAILED
3. Job rolls up to COMPLETED, FAILED, or PARTIAL

Poll with GET /api/v1/jobs/:id. Full status tables and response shapes: Endpoints — Poll job status.

Discovery

GET /api/v1

Returns the endpoint list and requirements (no auth).

Next

See Endpoints for curl examples covering upload, jobs, layouts, watermarks, playlists, batch, resolutions, categories, and errors. For composition concepts (templates, blur, fine-tuning, fonts), see Video editing.