mirror of
https://git.atakanozban.com/Songs2VID/songs2vid.git
synced 2026-11-14 21:29:49 +01:00
67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
|
# 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/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:
|
|||
|
|
|
|||
|
|
```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 and requirements (no auth). Useful as a machine-readable catalog of what this instance exposes.
|
|||
|
|
|
|||
|
|
## Next
|
|||
|
|
|
|||
|
|
See [Endpoints](./endpoints.md) for curl examples. Hosted HTML docs: [docs.songs2vid.com/docs/api/overview](https://docs.songs2vid.com/docs/api/overview).
|