Align preview typography with FFmpeg output, add video/song title split, and ship OSS updates.
Separate YouTube video titles from on-video song/artist fields with Pro gating, serve curated fonts and watermark assets for 1:1 preview parity, and include billing/API/docs/deploy stack for self-hosted release. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Atakan Doğan Özban
co-authored by
Cursor
Cursor
parent
682020ff5a
commit
c8015937f9
@@ -0,0 +1,420 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Endpoints
|
||||
|
||||
Set these for the examples below:
|
||||
|
||||
```bash
|
||||
export BASE_URL="http://localhost:3000" # local / self-hosted app
|
||||
export API_KEY="s2yt_live_your_key_here"
|
||||
```
|
||||
|
||||
Local API docs: with `npm run dev:all` (or `npm run docs:dev`) open [http://localhost:3001/docs/api/overview](http://localhost:3001/docs/api/overview).
|
||||
|
||||
## Discovery
|
||||
|
||||
```bash
|
||||
curl "$BASE_URL/api/v1"
|
||||
```
|
||||
|
||||
Returns the endpoint list and requirements (**no auth**).
|
||||
|
||||
## Upload a file (two-step)
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/upload" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-F "file=@cover.jpg" \
|
||||
-F "type=image"
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/upload" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-F "file=@track1.mp3" \
|
||||
-F "type=audio"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Optional: PNG watermark logo
|
||||
curl -X POST "$BASE_URL/api/v1/upload" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-F "file=@logo.png" \
|
||||
-F "type=logo"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Optional: custom watermark font (.ttf / .otf, max 10 MB)
|
||||
curl -X POST "$BASE_URL/api/v1/upload" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-F "file=@Brand.ttf" \
|
||||
-F "type=font"
|
||||
```
|
||||
|
||||
### Request fields
|
||||
|
||||
| Field | Required | Notes |
|
||||
|-------|----------|--------|
|
||||
| `file` | Yes | Multipart file |
|
||||
| `type` | Yes | `image` \| `audio` \| `logo` \| `font` |
|
||||
|
||||
### Allowed files (self-hosted)
|
||||
|
||||
| `type` | Formats | Max size |
|
||||
|--------|---------|----------|
|
||||
| `image` | JPEG, PNG, WebP, GIF | 500 MB |
|
||||
| `audio` | MP3, WAV, FLAC (also accepts related MIME types) | 500 MB |
|
||||
| `logo` | PNG only | 500 MB |
|
||||
| `font` | `.ttf` / `.otf` | **10 MB** |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/uploads/.../track.mp3",
|
||||
"filename": "track.mp3",
|
||||
"size": 4123456,
|
||||
"audioTags": {
|
||||
"title": "Song Title",
|
||||
"artist": "Artist Name",
|
||||
"album": "Album",
|
||||
"genre": "Electronic",
|
||||
"year": "2024"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Notes |
|
||||
|-------|--------|
|
||||
| `path` | Absolute path on the server — pass this into job create |
|
||||
| `filename` | Original filename |
|
||||
| `size` | Bytes |
|
||||
| `audioTags` | Present for MP3 when tags are readable; otherwise `null`. Fields may be omitted when missing in the file |
|
||||
|
||||
Upload the shared cover once (`type=image`), each audio (`type=audio`), optionally a PNG logo (`type=logo`), and optionally a custom font (`type=font`) for text watermarks.
|
||||
|
||||
## Create job from paths (recommended)
|
||||
|
||||
Use the exact `path` strings returned by upload. Add one `items[]` entry per track.
|
||||
|
||||
Self-hosted deployments unlock per-track covers, custom watermarks/fonts, and art-track layouts. Max batch size: **100**.
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/jobs" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"imagePath": "/uploads/.../cover.jpg",
|
||||
"items": [{
|
||||
"audioPath": "/uploads/.../track.mp3",
|
||||
"audioFilename": "track.mp3",
|
||||
"metadata": {
|
||||
"title": "My Track",
|
||||
"artist": "My Artist",
|
||||
"description": "",
|
||||
"tags": "electronic",
|
||||
"privacy": "PUBLIC",
|
||||
"categoryId": "10",
|
||||
"resolution": "1920x1080",
|
||||
"notifySubscribers": true,
|
||||
"madeForKids": false,
|
||||
"embeddable": true,
|
||||
"creativeCommons": false,
|
||||
"includeWatermark": true,
|
||||
"imagePath": "/uploads/.../track-cover.jpg",
|
||||
"layout": {
|
||||
"template": "COVER_LEFT_TEXT_RIGHT",
|
||||
"blurAmount": 60,
|
||||
"blurOpacity": 85,
|
||||
"textPadding": 48,
|
||||
"titleArtistGap": 12,
|
||||
"textOffsetX": 0,
|
||||
"textOffsetY": 0
|
||||
},
|
||||
"watermark": {
|
||||
"mode": "text",
|
||||
"text": "My Label",
|
||||
"fontKey": "montserrat",
|
||||
"position": "bottom-right",
|
||||
"offsetX": 24,
|
||||
"offsetY": 24
|
||||
},
|
||||
"playlistId": null
|
||||
}
|
||||
}]
|
||||
}'
|
||||
```
|
||||
|
||||
### Success response
|
||||
|
||||
```json
|
||||
{
|
||||
"jobId": "clxxxxxxxx",
|
||||
"itemCount": 1,
|
||||
"status": "PENDING",
|
||||
"playlist": null
|
||||
}
|
||||
```
|
||||
|
||||
`playlist` is set when you pass `createPlaylist` (see [YouTube playlists](#youtube-playlists)).
|
||||
|
||||
### Metadata fields
|
||||
|
||||
| Field | Type | Notes |
|
||||
|-------|------|--------|
|
||||
| `title` | string | Video title |
|
||||
| `artist` | string \| null | On-video artist line (max **80**) |
|
||||
| `description` | string | YouTube description |
|
||||
| `tags` | string | Comma-separated (quoted tags supported) |
|
||||
| `privacy` | string | `PUBLIC` \| `PRIVATE` \| `UNLISTED` |
|
||||
| `categoryId` | string | YouTube category ID (see below) |
|
||||
| `resolution` | string | One of the supported values (see below) |
|
||||
| `notifySubscribers` | boolean | YouTube upload notify flag |
|
||||
| `madeForKids` | boolean | COPPA / made for kids |
|
||||
| `embeddable` | boolean | Allow embedding |
|
||||
| `creativeCommons` | boolean | CC license vs standard YouTube |
|
||||
| `includeWatermark` | boolean | Apply watermark settings |
|
||||
| `imagePath` | string \| null | Per-track cover (overrides job `imagePath`) |
|
||||
| `playlistId` | string \| null | Existing playlist ID |
|
||||
| `layout` | object | Art-track layout (see below) |
|
||||
| `watermark` | object | Watermark settings (see below) |
|
||||
|
||||
Snake_case aliases are accepted for layout/watermark fields (e.g. `blur_amount`, `layout_template`).
|
||||
|
||||
### Resolutions
|
||||
|
||||
| Value | Aspect |
|
||||
|-------|--------|
|
||||
| `1920x1080` | 16:9 |
|
||||
| `1280x720` | 16:9 |
|
||||
| `854x480` | 16:9 |
|
||||
| `720x720` | 1:1 |
|
||||
| `640x360` | 16:9 |
|
||||
| `426x240` | 16:9 |
|
||||
|
||||
Self-hosted allows all of these.
|
||||
|
||||
### YouTube categories
|
||||
|
||||
Pass `categoryId` as a string ID. Common values:
|
||||
|
||||
| ID | Name |
|
||||
|----|------|
|
||||
| `1` | Film & Animation |
|
||||
| `2` | Autos & Vehicles |
|
||||
| `10` | Music |
|
||||
| `15` | Pets & Animals |
|
||||
| `17` | Sports |
|
||||
| `19` | Travel & Events |
|
||||
| `20` | Gaming |
|
||||
| `22` | People & Blogs |
|
||||
| `23` | Comedy |
|
||||
| `24` | Entertainment |
|
||||
| `25` | News & Politics |
|
||||
| `26` | Howto & Style |
|
||||
| `27` | Education |
|
||||
| `28` | Science & Technology |
|
||||
| `29` | Nonprofits & Activism |
|
||||
|
||||
Official reference: [YouTube Data API — VideoCategories](https://developers.google.com/youtube/v3/docs/videoCategories/list).
|
||||
|
||||
### Watermark fields
|
||||
|
||||
`watermark.position`: `top-left` | `top-right` | `bottom-left` | `bottom-right` | `center`.
|
||||
|
||||
`watermark.mode`: `none` | `default` | `text` | `logo` (logo requires prior `type=logo` upload; set `logoPath`).
|
||||
|
||||
`watermark.offsetX` / `offsetY`: `0`–`200` (default `20`) — pixels from the chosen anchor.
|
||||
|
||||
`watermark.fontKey` (text mode): `system` | `inter` | `montserrat` | `roboto` | `oswald` | `playfair` | `custom`. For `custom`, upload with `type=font` first and set `fontPath` to the returned path. Text max length: **80**.
|
||||
|
||||
For a full walkthrough of composition controls, see [Video editing](../video-editing.md).
|
||||
|
||||
### Art-track layouts
|
||||
|
||||
`metadata.layout.template` (or flat `layout_template` / `layoutTemplate`):
|
||||
|
||||
| Enum | Description |
|
||||
|------|-------------|
|
||||
| `COVER_LEFT_TEXT_RIGHT` | Cover left, title & artist right |
|
||||
| `COVER_TOP_TEXT_BOTTOM` | Cover top, title & artist below |
|
||||
| `COVER_RIGHT_TEXT_LEFT` | Cover right, title & artist left |
|
||||
| `CENTERED_COMPACT` | Centered cover + text stack |
|
||||
|
||||
Optional fine-tuning (clamped; camelCase or snake_case):
|
||||
|
||||
| Field | Range | Default | Purpose |
|
||||
|-------|-------|---------|---------|
|
||||
| `blurAmount` / `blur_amount` | 0–100 | 55 | Background `boxblur` intensity |
|
||||
| `blurOpacity` / `blur_opacity` | 0–100 | 100 | Blurred fill vs black |
|
||||
| `textPadding` / `text_padding` | 16–120 | 48 | Padding around cover and text |
|
||||
| `titleArtistGap` / `title_artist_gap` | 0–64 | 10 | Space between title and artist |
|
||||
| `textOffsetX` / `text_offset_x` | −120–120 | 0 | Shift text block horizontally |
|
||||
| `textOffsetY` / `text_offset_y` | −120–120 | 0 | Shift text block vertically |
|
||||
|
||||
Also set `metadata.artist` (max 80) for the on-video artist line.
|
||||
|
||||
Omit `layout.template` (or use classic letterbox) when you only want a black-padded cover. Free-form cover coordinates (`x`, `y`, `coverX`, …) and layout-level `offsetX`/`offsetY` are **rejected** (use `textOffsetX`/`textOffsetY` instead; watermark offsets stay under `watermark`).
|
||||
|
||||
Invalid template strings return **400**:
|
||||
|
||||
```json
|
||||
{ "error": "Invalid layout template. Refer to API documentation for valid enum values." }
|
||||
```
|
||||
|
||||
## YouTube playlists
|
||||
|
||||
List existing playlists, create a new one, or create one inline when starting a job. Pass `playlistId` in item metadata / batch `defaults`, or use `createPlaylist` to make a playlist and attach all videos to it.
|
||||
|
||||
Privacy may be `public`, `unlisted`, or `private`. If playlist permission was just added, sign out and sign in again so OAuth includes `youtube.force-ssl`.
|
||||
|
||||
YouTube playlist API reference: [Playlists: insert](https://developers.google.com/youtube/v3/docs/playlists/insert).
|
||||
|
||||
```bash
|
||||
# List playlists
|
||||
curl "$BASE_URL/api/v1/playlists" \
|
||||
-H "Authorization: Bearer $API_KEY"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Create a playlist
|
||||
curl -X POST "$BASE_URL/api/v1/playlists" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title":"My Album","description":"From Songs2VID","privacy":"unlisted"}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"playlistId": "PLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||
}
|
||||
```
|
||||
|
||||
Or create one inline with a job / batch request:
|
||||
|
||||
```json
|
||||
{
|
||||
"createPlaylist": {
|
||||
"title": "My Album",
|
||||
"description": "Uploaded via Songs2VID",
|
||||
"privacy": "private"
|
||||
},
|
||||
"defaults": { "privacy": "PUBLIC" },
|
||||
"items": [{ "title": "Track One" }]
|
||||
}
|
||||
```
|
||||
|
||||
## One-shot batch (small packs only)
|
||||
|
||||
Upload one cover image and a few audio files in a single multipart request. **Not recommended for large batches** — use two-step if you see FormData parse errors.
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/jobs/batch" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-F "image=@cover.jpg" \
|
||||
-F "audio=@track1.mp3" \
|
||||
-F "audio=@track2.mp3" \
|
||||
-F 'metadata={"createPlaylist":{"title":"My Album","privacy":"unlisted"},"defaults":{"privacy":"PUBLIC"},"items":[{"title":"Track One"},{"title":"Track Two"}]}'
|
||||
```
|
||||
|
||||
Optional `metadata` JSON supports `defaults` applied to every item and per-item overrides in `items`. Item order should match the order of `audio` files.
|
||||
|
||||
When item metadata is omitted, batch defaults include privacy `PUBLIC`, resolution `1920x1080`, and watermark off unless overridden in `defaults`.
|
||||
|
||||
**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
|
||||
|
||||
## Poll job status
|
||||
|
||||
```bash
|
||||
curl "$BASE_URL/api/v1/jobs/JOB_ID" \
|
||||
-H "Authorization: Bearer $API_KEY"
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "$BASE_URL/api/v1/jobs?limit=10" \
|
||||
-H "Authorization: Bearer $API_KEY"
|
||||
```
|
||||
|
||||
`GET /api/v1/jobs` accepts `limit` (default **20**, max **100**).
|
||||
|
||||
### Job response
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "clxxxxxxxx",
|
||||
"status": "PROCESSING",
|
||||
"createdAt": "2026-07-25T12:00:00.000Z",
|
||||
"completedAt": null,
|
||||
"items": [
|
||||
{
|
||||
"id": "clitemxxx",
|
||||
"audioFilename": "track.mp3",
|
||||
"title": "My Track",
|
||||
"description": "",
|
||||
"tags": "electronic",
|
||||
"privacy": "PUBLIC",
|
||||
"categoryId": "10",
|
||||
"resolution": "1920x1080",
|
||||
"status": "ENCODING",
|
||||
"youtubeVideoId": null,
|
||||
"error": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Job statuses
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `PENDING` | Queued; worker has not started |
|
||||
| `PROCESSING` | At least one item is encoding or uploading |
|
||||
| `COMPLETED` | All items succeeded |
|
||||
| `FAILED` | All items failed |
|
||||
| `PARTIAL` | Mix of completed and failed items |
|
||||
|
||||
### Item statuses
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `PENDING` | Waiting in the queue |
|
||||
| `ENCODING` | FFmpeg is building the video |
|
||||
| `UPLOADING` | Uploading to YouTube |
|
||||
| `COMPLETED` | Live on YouTube (`youtubeVideoId` set) |
|
||||
| `FAILED` | Failed (`error` contains a message) |
|
||||
|
||||
### Pipeline notes
|
||||
|
||||
- Each item is encoded, then uploaded; the local MP4 is removed after a successful upload
|
||||
- Queue retries: **2** attempts with exponential backoff (5s base)
|
||||
- Worker concurrency: **2** items in parallel
|
||||
- On item failure, reserved allowance for that item is released
|
||||
|
||||
YouTube upload limits (channel daily caps, etc.) are enforced by Google, not Songs2VID. See [YouTube Data API — Quota and compliance](https://developers.google.com/youtube/v3/guides/quota_and_compliance_audits).
|
||||
|
||||
## HTTP errors
|
||||
|
||||
| Status | When |
|
||||
|--------|------|
|
||||
| `400` | Validation error (bad file type, invalid layout, missing fields, bad JSON) |
|
||||
| `401` | Missing or invalid API key |
|
||||
| `403` | YouTube not connected, or edition/plan does not allow API features |
|
||||
| `404` | Job not found |
|
||||
| `429` | API rate limit exceeded — body includes `retryAfterSeconds`; header `Retry-After` is set |
|
||||
|
||||
Example rate-limit body:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "API rate limit exceeded. Try again shortly.",
|
||||
"retryAfterSeconds": 42
|
||||
}
|
||||
```
|
||||
|
||||
Self-hosted rate limits are effectively unlimited for normal use. See [API overview](./overview.md).
|
||||
Reference in New Issue
Block a user