Add n8n community node, /api/v1/render alias, and job webhooks for OSS automation.

Payment-free self-hosted builds keep full API access with optional webhookUrl callbacks and the published n8n-nodes-songs2vid package source under integrations/n8n.

docs/api/endpoints.md

@@ -84,16 +84,21 @@ curl -X POST "$BASE_URL/api/v1/upload" \
 
 `audioTags` is present for MP3 when tags are readable; otherwise `null`.
 
-## Create job from paths (recommended)
+## Create job / render from paths (recommended)
 
 Self-hosted unlocks per-track covers, custom watermarks/fonts, and art-track layouts. Max batch size: **100**. Watermarks are optional — nothing forces the default Songs2VID badge.
 
+`POST /api/v1/render` is an **n8n-friendly alias** of `POST /api/v1/jobs` (identical body and response). `GET /api/v1/render` lists jobs like `GET /api/v1/jobs`.
+
+Optional `webhookUrl` (absolute `http(s)` URL) makes Songs2VID POST JSON when items/jobs finish — preferred for n8n.
+
 ```bash
-curl -X POST "$BASE_URL/api/v1/jobs" \
+curl -X POST "$BASE_URL/api/v1/render" \
   -H "Authorization: Bearer $API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "imagePath": "/uploads/.../cover.jpg",
+    "webhookUrl": "https://your-n8n.example/webhook/songs2vid-complete",
     "items": [{
       "audioPath": "/uploads/.../track.mp3",
       "audioFilename": "track.mp3",
@@ -134,6 +139,8 @@ curl -X POST "$BASE_URL/api/v1/jobs" \
   }'
 ```
 
+Equivalent path: `POST $BASE_URL/api/v1/jobs` with the same JSON.
+
 ### Success response
 
 ```json
@@ -141,10 +148,51 @@ curl -X POST "$BASE_URL/api/v1/jobs" \
   "jobId": "clxxxxxxxx",
   "itemCount": 1,
   "status": "PENDING",
+  "statusUrl": "/api/v1/jobs/clxxxxxxxx",
+  "webhookUrl": "https://your-n8n.example/webhook/songs2vid-complete",
   "playlist": null
 }
 ```
 
+### Webhook payload
+
+| `event` | Meaning |
+|---------|---------|
+| `job.item.completed` | One track finished (`youtubeVideoId` set) |
+| `job.item.failed` | One track failed (`error` set) |
+| `job.completed` | All items succeeded |
+| `job.failed` | All items failed |
+| `job.partial` | Mix of success and failure |
+
+Community node: [`n8n-nodes-songs2vid`](https://www.npmjs.com/package/n8n-nodes-songs2vid) — see [docs/n8n.md](../n8n.md) and [docs.songs2vid.com/docs/n8n](https://docs.songs2vid.com/docs/n8n).
+
+<details>
+<summary>Legacy example without webhook (same metadata shape)</summary>
+
+```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 Artist - My Track (Official Audio)",
+        "songTitle": "My Track",
+        "artist": "My Artist",
+        "privacy": "PUBLIC",
+        "categoryId": "10",
+        "resolution": "1920x1080",
+        "includeWatermark": false
+      }
+    }]
+  }'
+```
+
+</details>
+
 ### Metadata fields
 
 | Field | Type | Notes |

docs/api/overview.md

@@ -31,10 +31,12 @@ If a limit is hit, the response is **429** with `retryAfterSeconds` and a `Retry
 ### 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)
+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:
@@ -63,4 +65,4 @@ Returns the endpoint list, requirements, `layoutTemplates` (every art-track enum
 
 ## Next
 
-See [Endpoints](./endpoints.md) for curl examples. Hosted HTML docs: [docs.songs2vid.com/docs/api/overview](https://docs.songs2vid.com/docs/api/overview).
+See [Endpoints](./endpoints.md) for curl examples. n8n: [docs/n8n.md](../n8n.md). Hosted HTML docs: [docs.songs2vid.com/docs/api/overview](https://docs.songs2vid.com/docs/api/overview).