songs2vid/docs/api/overview.md

API overview

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

Keys start with s2yt_live_ and are shown once at creation. The OSS / Docker image always allows API use — there is no plan, credit, or paywall gate.

There are no billing endpoints in this edition.

Authentication

Send the key on every request:

Authorization: Bearer s2yt_live_your_key_here

Requirements:

• YouTube channel connected (sign in with Google OAuth that includes YouTube scopes)

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

Rate limits

Self-hosted OSS uses 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. 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.

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.

Discovery

GET /api/v1

Returns the endpoint list, requirements, layoutTemplates (every art-track enum id + label, including LOWER_LEFT_COVER_TEXT / LOWER_RIGHT_COVER_TEXT), and compositionFamilies (UI grouping for mirrored left/right variants). No auth required.

Next

See Endpoints for curl examples. Hosted HTML docs: docs.songs2vid.com/docs/api/overview.