Skip to main content
POST
/
api
/
content
/
create
cURL
curl --request POST \
  --url https://recoup-api.vercel.app/api/content/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "artist_account_id": "1873859c-dd37-4e9a-9bac-80d3558527a9",
  "template": "artist-caption-stage",
  "lipsync": false,
  "caption_length": "none",
  "upscale": false,
  "batch": 1,
  "songs": [
    "hiccups",
    "https://example.com/unreleased-track.mp3"
  ],
  "images": [
    "https://example.com/face.png"
  ]
}
'
{
  "runIds": [
    "run_abc123def456"
  ],
  "status": "triggered",
  "artist_account_id": "1873859c-dd37-4e9a-9bac-80d3558527a9",
  "template": null,
  "lipsync": false,
  "failed": 0
}

Documentation Index

Fetch the complete documentation index at: https://developers.recoupable.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-api-key
string
header
required

Your Recoup API key. Learn more.

Body

application/json

Content creation parameters including the target artist and optional template/workflow settings

Parameters for triggering the content creation pipeline.

​
artist_account_id
string<uuid>
required

UUID of the artist account to create content for. Use GET /api/artists to find artist account IDs.

Example:

"1873859c-dd37-4e9a-9bac-80d3558527a9"

​
template
string

Optional template ID for content generation. Defines the visual style, scene, and prompt configuration. When omitted, the pipeline runs in malleable mode using only the params you provide. See GET /api/content/templates for available options.

Example:

"artist-caption-stage"

​
lipsync
boolean

Whether to generate video with lip-synced audio. When true, uses an audio-to-video model that bakes audio into the video for lip movement. When false, generates video from the image alone and overlays audio in post. If omitted, the template's default workflow is used.

Example:

false

​
caption_length
enum<string>
default:none

Controls the length of the generated caption text. none skips caption generation. short produces 1-2 lines (punchy, minimal). medium produces 1-2 sentences. long produces a paragraph (stream of consciousness style). Defaults to none.

Available options:
none,
short,
medium,
long
Example:

"none"

​
upscale
boolean
default:false

Whether to upscale the generated image and video for higher resolution and detail. Adds approximately 2 minutes to the pipeline. Defaults to false.

Example:

false

​
batch
integer
default:1

Number of videos to generate in parallel. Each video independently selects a random reference image, song clip, and mood variation. The response always returns runIds as an array. Defaults to 1.

Required range: 1 <= x <= 30
Example:

1

​
songs
string[]

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"
]
​
images
string<uri>[]

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"]

Response

Pipeline triggered successfully. Returns runIds — an array of run IDs. Poll each via GET /api/tasks/runs to check progress.

Confirmation that the content creation pipeline has been triggered. Always returns runIds as an array — even for a single run, it contains one element.

​
runIds
string[]
required

Array of run IDs. Poll each via GET /api/tasks/runs. For single runs this contains one element.

Example:
["run_abc123def456"]
​
status
enum<string>
required

Indicates the pipeline has been triggered

Available options:
triggered
​
artist_account_id
string<uuid>
required

UUID of the artist account the pipeline is running for

Example:

"1873859c-dd37-4e9a-9bac-80d3558527a9"

​
template
string | null

Template ID when a preset pipeline is used; null in malleable mode.

Example:

null

​
lipsync
boolean

Whether lip-sync mode is enabled

Example:

false

​
failed
integer

Number of triggers that failed. Only present when some triggers failed.

Example:

0