API REFERENCE

Create Content

On this page

POST/api/content/create

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 — an array of run IDs that can each be polled via GET /api/tasks/runs.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/content/create' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "artist_account_id": "1873859c-dd37-4e9a-9bac-80d3558527a9"
}'

Request body required

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

application/json

artist_account_idstringrequired

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

format: uuid

templatestring

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.

lipsyncboolean

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.

caption_lengthstring · enum

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.

Values: "none", "short", "medium", "long"

Default: "none"

upscaleboolean

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

Default: false

batchinteger

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.

Default: 1

minimum: 1 · maximum: 30

songsarray<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.

Item properties

string

imagesarray<string>

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.

Item properties

string

Responses

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

application/json

runIdsarray<string>required

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

Item properties

string

statusstring · enumrequired

Indicates the pipeline has been triggered

Values: "triggered"

artist_account_idstringrequired

UUID of the artist account the pipeline is running for

format: uuid

templatestring | null

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

lipsyncboolean

Whether lip-sync mode is enabled

failedinteger

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

400Validation failed — missing artist identifier, artist is missing required files, or template not found

application/json

errorstringrequired

Human-readable error summary

readyboolean

Always false when this error is returned

missingarray<ContentMissingFile>

List of missing files with severity and fix instructions. Only present when the artist fails validation.

Item properties

filestringrequired

Relative path of the missing file within the artist directory

severitystring · enumrequired

required means the pipeline will fail without this file. recommended means the pipeline will run but output quality is degraded.

Values: "required", "recommended"

descriptionstringrequired

What this file is used for in the pipeline

fixstringrequired

Actionable instructions for creating or adding the missing file

available_templatesarray<string>

List of valid template names. Only present when the requested template was not found.

Item properties

string

401Unauthorized — invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

404Artist not found — the provided artist_account_id does not match any artist

application/json

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "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` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Content creation parameters including the target artist and optional template/workflow settings",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContentCreateRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Pipeline triggered successfully. Returns `runIds` — an array of run IDs. Poll each via [GET /api/tasks/runs](/api-reference/tasks/runs) to check progress.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentCreateResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation failed — missing artist identifier, artist is missing required files, or template not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentCreateErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Artist not found — the provided artist_account_id does not match any artist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    }
  }
}