From 0fddf77e9c5d0c5a8a1b4df3d6935e4eda2f3524 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Tue, 31 Mar 2026 11:40:13 -0500 Subject: [PATCH 1/2] docs: add attached_audio_url and attached_image_url to content/create Document the new optional attachment parameters for POST /api/content/create. These allow callers to provide custom audio and face-guide images that override the defaults from the artist's GitHub repo. Companion to recoupable/api#381 and recoupable/tasks#116. Co-Authored-By: Claude Opus 4.6 (1M context) --- api-reference/openapi.json | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index ed2ddb5..9410be8 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -3785,7 +3785,7 @@ }, "/api/content/create": { "post": { - "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs), then triggers a background task that generates a short-form video. Returns `runIds` \u2014 an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs). Authentication is handled via the x-api-key header.", + "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden by attached media, then triggers a background task that generates a short-form video. Returns `runIds` \u2014 an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs). Authentication is handled via the x-api-key header.", "requestBody": { "description": "Content creation parameters including the target artist and optional template/workflow settings", "required": true, @@ -10738,6 +10738,18 @@ }, "description": "Optional list of song slugs to restrict which songs the pipeline picks from. When omitted, all songs in the artist's `songs/` directory are eligible. Song slugs match the filename without extension (e.g. `\"hiccups\"` for `hiccups.mp3`). Useful for targeting a specific release — pass all track slugs from an EP or album.", "example": ["hiccups", "adhd"] + }, + "attached_audio_url": { + "type": "string", + "format": "uri", + "description": "Public URL of an audio file to use instead of selecting from the artist's Git repo songs. When provided, the pipeline downloads this audio, transcribes it, and selects a clip from it. Overrides the `songs` parameter.", + "example": "https://example.com/my-song.mp3" + }, + "attached_image_url": { + "type": "string", + "format": "uri", + "description": "Public URL of an image to use as the face guide instead of the artist's `face-guide.png` from their GitHub repo. Useful when the caller wants to override the default face reference.", + "example": "https://example.com/face.png" } }, "required": [ From 427450260bd64e67049888acc29dfbf290fba332 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Tue, 31 Mar 2026 11:45:46 -0500 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20implement=20design=20feedback=20?= =?UTF-8?q?=E2=80=94=20songs=20accepts=20URLs,=20images=20array=20replaces?= =?UTF-8?q?=20attached=5Fimage=5Furl?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address sweetmantech's review: - Extend songs param to accept both slugs and public URLs (no separate attached_audio_url) - Replace attached_image_url with images array to match songs pattern (KISS) - Add Create Content to Guides navbar above Create Sandbox Co-Authored-By: Claude Opus 4.6 (1M context) --- api-reference/openapi.json | 25 +++++++++++-------------- docs.json | 1 + 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 9410be8..732cda6 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -3785,7 +3785,7 @@ }, "/api/content/create": { "post": { - "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden by attached media, then triggers a background task that generates a short-form video. Returns `runIds` \u2014 an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs). Authentication is handled via the x-api-key header.", + "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` \u2014 an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs). Authentication is handled via the x-api-key header.", "requestBody": { "description": "Content creation parameters including the target artist and optional template/workflow settings", "required": true, @@ -10736,20 +10736,17 @@ "items": { "type": "string" }, - "description": "Optional list of song slugs to restrict which songs the pipeline picks from. When omitted, all songs in the artist's `songs/` directory are eligible. Song slugs match the filename without extension (e.g. `\"hiccups\"` for `hiccups.mp3`). Useful for targeting a specific release — pass all track slugs from an EP or album.", - "example": ["hiccups", "adhd"] + "description": "Optional list of song slugs or public URLs to use for the audio track. Song slugs match filenames without extension from the artist's `songs/` directory (e.g. `\"hiccups\"` for `hiccups.mp3`). Public URLs (e.g. `\"https://example.com/my-song.mp3\"`) are downloaded, transcribed, and clipped directly — bypassing the Git repo. When omitted, all songs in the artist's repo are eligible.", + "example": ["hiccups", "https://example.com/unreleased-track.mp3"] }, - "attached_audio_url": { - "type": "string", - "format": "uri", - "description": "Public URL of an audio file to use instead of selecting from the artist's Git repo songs. When provided, the pipeline downloads this audio, transcribes it, and selects a clip from it. Overrides the `songs` parameter.", - "example": "https://example.com/my-song.mp3" - }, - "attached_image_url": { - "type": "string", - "format": "uri", - "description": "Public URL of an image to use as the face guide instead of the artist's `face-guide.png` from their GitHub repo. Useful when the caller wants to override the default face reference.", - "example": "https://example.com/face.png" + "images": { + "type": "array", + "items": { + "type": "string", + "format": "uri" + }, + "description": "Optional list of public image URLs to use as face guides instead of the artist's default `face-guide.png` from their GitHub repo. The first image is used as the primary face guide. Useful when the caller wants to override the default face reference.", + "example": ["https://example.com/face.png"] } }, "required": [ diff --git a/docs.json b/docs.json index 058e75d..e5268b4 100644 --- a/docs.json +++ b/docs.json @@ -21,6 +21,7 @@ "cli", "mcp", "authentication", + "api-reference/content/create", "api-reference/sandboxes/create" ] },