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:

```http
Authorization: Bearer s2yt_live_your_key_here
```

Requirements:

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

OAuth setup: root [README](../../README.md) and Google’s [OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server). YouTube scopes/API: [YouTube Data API Overview](https://developers.google.com/youtube/v3/getting-started).

## 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](./endpoints.md#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. Max batch size is **100** tracks per job.

Prefer `webhookUrl` for n8n so long encodes do not block an HTTP Request node. Details: [n8n](../n8n.md).

### 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:

```text
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

```http
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](./endpoints.md) for curl examples. n8n: [docs/n8n.md](../n8n.md). Primary source: [git.atakanozban.com/Songs2VID](https://git.atakanozban.com/Songs2VID). Hosted HTML docs: [docs.songs2vid.com/docs/api/overview](https://docs.songs2vid.com/docs/api/overview).