API overview

Programmatic uploads, renders, playlists, and webhooks for Songs2VID.

Editions

Edition	Base URL	Who can use the API
Cloud (SaaS)	https://songs2vid.com	Developer & Automation (€15) or Enterprise only
Self-hosted OSS	Your deploy (e.g. http://localhost:3000)	Always on — no plan or credit gate

Independent Producer (€7) is Web UI only. Calling REST with a Producer (or Free) key returns 403:

{ "error": "REST API access requires the Developer & Automation plan." }

Generate keys under Dashboard → Settings → API access. Tokens start with s2yt_live_ and are shown once at creation.

For zero-code automation, see the n8n integration guide — the community node maps 1:1 to every /api/v1 endpoint below.

Authentication

Send the key on every authenticated request (preferred header):

Authorization: Bearer s2yt_live_your_key_here

There is no separate X-API-Key header today — use Authorization: Bearer.

Requirements (cloud):

• Plan with API access (DEVELOPER_PRO or ENTERPRISE)
• YouTube channel connected via dashboard Google OAuth (YouTube scopes)

OAuth setup: Getting started and Google’s OAuth 2.0 for Web Server Applications.

Plans, quotas & media quality

Plan	Monthly renders	REST API	Encode audio	Watermark
Free	3 (UI)	No	192 kbps AAC	Songs2VID badge forced
Independent Producer (€7)	30 (UI)	No	320 kbps	Optional / custom
Developer & Automation (€15)	60 (UI + API)	Yes · priority queue	320 kbps	Optional / custom
Enterprise	Custom	Yes · priority queue	320 kbps	Optional / custom
Self-hosted OSS	Effectively unlimited	Yes	320 kbps	Full control

Audio bitrate is applied by the worker from the account plan — it is not a request body field. Free cannot opt into 320 kbps via API.

Quota exhaustion on create returns 402 (jobs/render) with a message such as "Payment Required: no credits remaining." or "Not enough credits...".

Rate limits

Edition	Limit
Cloud Developer+	60 requests / minute / API key (plus any approved bonus)
Self-hosted	Very high ceiling (effectively unlimited for normal automation)

On limit: 429 with body retryAfterSeconds and header Retry-After. 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/render (alias of /api/v1/jobs) — JSON paths + optional webhookUrl

This avoids huge multipart bodies.

Edition	Max tracks / job
Developer	10
Enterprise	50
Self-hosted	100

One-shot batch: small packs only

POST /api/v1/jobs/batch accepts one cover and a few audios in one multipart request. Large bodies often fail with failed to parse body as FormData. Prefer two-step for albums.

n8n / async

Pass webhookUrl on job create so n8n does not block on long encodes. Details: n8n — Webhooks vs polling.

Job lifecycle

1. Create job → PENDING (response includes jobId, statusUrl, optional webhookUrl)
2. Worker → item ENCODING → UPLOADING → COMPLETED or FAILED
3. Job rolls up to COMPLETED, FAILED, or PARTIAL
4. Optional HTTPS POST to webhookUrl on item/job terminal events

Poll with GET /api/v1/jobs/:id.

Discovery

GET /api/v1

Returns endpoint catalog, auth note, rate-limit summary, layoutTemplates, and compositionFamilies. No auth required.

Next

• Endpoints — curl examples for every route
• n8n integration — community node, recipes, copy-paste workflow
• Endpoints — every /api/v1/* route with curl examples
• Video editing — layouts, blur, fonts, watermarks