# Create Content

Source: https://recoupable.dev/docs/api-reference/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](/api-reference/tasks/runs).

## POST /api/content/create

Full OpenAPI specification: https://recoupable.dev/docs/spec/content.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Content",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/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 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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContentCreateRequest": {
        "type": "object",
        "description": "Parameters for triggering the content creation pipeline.",
        "properties": {
          "artist_account_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the artist account to create content for. Use [GET /api/artists](/api-reference/artists/list) to find artist account IDs.",
            "example": "1873859c-dd37-4e9a-9bac-80d3558527a9"
          },
          "template": {
            "type": "string",
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "enum": [
              "none",
              "short",
              "medium",
              "long"
            ],
            "description": "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`.",
            "default": "none",
            "example": "none"
          },
          "upscale": {
            "type": "boolean",
            "description": "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,
            "example": false
          },
          "batch": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "description": "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,
            "example": 1
          },
          "songs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "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"
            ]
          },
          "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": [
          "artist_account_id"
        ]
      },
      "ContentCreateResponse": {
        "type": "object",
        "required": [
          "runIds",
          "status",
          "artist_account_id"
        ],
        "description": "Confirmation that the content creation pipeline has been triggered. Always returns `runIds` as an array — even for a single run, it contains one element.",
        "properties": {
          "runIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of run IDs. Poll each via [GET /api/tasks/runs](/api-reference/tasks/runs). For single runs this contains one element.",
            "example": [
              "run_abc123def456"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "triggered"
            ],
            "description": "Indicates the pipeline has been triggered"
          },
          "artist_account_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the artist account the pipeline is running for",
            "example": "1873859c-dd37-4e9a-9bac-80d3558527a9"
          },
          "template": {
            "type": [
              "string",
              "null"
            ],
            "description": "Template ID when a preset pipeline is used; null in malleable mode.",
            "example": null
          },
          "lipsync": {
            "type": "boolean",
            "description": "Whether lip-sync mode is enabled",
            "example": false
          },
          "failed": {
            "type": "integer",
            "description": "Number of triggers that failed. Only present when some triggers failed.",
            "example": 0
          }
        }
      },
      "ContentCreateErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "description": "Returned when the artist is missing required files or the template is not found. Includes actionable instructions for resolving each issue.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error summary",
            "example": "Artist 'new-artist' is not ready for content creation"
          },
          "ready": {
            "type": "boolean",
            "description": "Always `false` when this error is returned",
            "example": false
          },
          "missing": {
            "type": "array",
            "description": "List of missing files with severity and fix instructions. Only present when the artist fails validation.",
            "items": {
              "$ref": "#/components/schemas/ContentMissingFile"
            }
          },
          "available_templates": {
            "type": "array",
            "description": "List of valid template names. Only present when the requested template was not found.",
            "items": {
              "type": "string"
            },
            "example": [
              "artist-caption-bedroom",
              "artist-caption-outside",
              "artist-caption-stage"
            ]
          }
        }
      },
      "ContentErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong",
            "example": "Unauthorized"
          }
        }
      },
      "ContentMissingFile": {
        "type": "object",
        "required": [
          "file",
          "severity",
          "description",
          "fix"
        ],
        "description": "A missing file that prevents or degrades content creation.",
        "properties": {
          "file": {
            "type": "string",
            "description": "Relative path of the missing file within the artist directory",
            "example": "context/images/face-guide.png"
          },
          "severity": {
            "type": "string",
            "enum": [
              "required",
              "recommended"
            ],
            "description": "`required` means the pipeline will fail without this file. `recommended` means the pipeline will run but output quality is degraded.",
            "example": "required"
          },
          "description": {
            "type": "string",
            "description": "What this file is used for in the pipeline",
            "example": "Face guide image used for AI image generation"
          },
          "fix": {
            "type": "string",
            "description": "Actionable instructions for creating or adding the missing file",
            "example": "Generate a face guide using fal-ai/nano-banana-pro/edit with 2-3 reference photos of the artist"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```