Skip to main content

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.

​
Overview

Recoup’s content API gives you seven independent primitives for generating and editing visual content. Each primitive does one thing well. You orchestrate them. Every primitive works without a template. Pass your own prompt, reference images, and parameters directly. Templates are optional shortcuts — opinionated creative recipes that pre-fill parameters for a specific look.

​
Primitives

PrimitiveEndpointWhat it does
Generate ImagePOST /api/content/imageCreate an image from a text prompt, optionally with a reference image for face/style
Generate VideoPOST /api/content/videoCreate a video — 6 modes: prompt, animate, reference, extend, first-last, lipsync
Generate CaptionPOST /api/content/captionGenerate on-screen text for social media videos
Transcribe AudioPOST /api/content/transcribeTranscribe audio to timestamped lyrics/text
Edit ContentPATCH /api/contentTrim, crop, resize, overlay text, or add audio — one processing pass
UpscalePOST /api/content/upscaleUpscale image or video resolution (up to 4x)
Analyze VideoPOST /api/content/analyzeAI video analysis — describe scenes, check quality, evaluate content
There is also POST /api/content/create which runs the full pipeline in one call — use it when you want a video without creative control over each step.

​
How It Works

​
Without a template (malleable mode)

Pass your own parameters directly to any primitive. Maximum creative control. 
# Generate an image with your own prompt
curl -X POST https://api.recoupable.com/api/content/image \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A moody portrait in a dimly lit room, front-facing phone camera"}'

# Generate a video from that image
curl -X POST https://api.recoupable.com/api/content/video \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "IMAGE_URL_FROM_ABOVE", "prompt": "subtle breathing motion, nearly still"}'

​
With a template (shortcut mode)

Pass a template ID and the primitive fills in prompts, reference images, and style rules automatically. You can still override any parameter. 
# Same image, but the template provides the prompt and reference images
curl -X POST https://api.recoupable.com/api/content/image \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "artist-caption-bedroom", "reference_image_url": "YOUR_FACE_IMAGE"}'
Use GET /api/content/templates to see available templates with descriptions.

​
Templates

A template is a complete creative recipe — it defines what a piece of content looks like across every primitive:
  • Image config: prompt, reference images, style rules (camera, lighting, composition)
  • Video config: mood variations, movement descriptions
  • Caption config: tone, formatting rules, example captions
  • Edit config: crop ratio, text overlay style, audio mixing
Templates are optional. They save time by pre-filling parameters with curated defaults. When you see customers repeatedly creating the same kind of content, that pattern becomes a template.

​
Override priority

When using a template, your explicit parameters always win:
  1. Your params — highest priority. What you pass overrides everything.
  2. Artist context — if the artist has a style guide, it personalizes the template.
  3. Template defaults — lowest priority. The recipe’s built-in values.

​
Video Modes

The video primitive supports 6 generation modes:
ModeWhat it doesRequired inputs
promptCreate from text descriptionprompt
animateAnimate a still imageimage_url, prompt
referenceUse image as style reference (not first frame)image_url, prompt
extendContinue an existing videovideo_url, prompt
first-lastTransition between two imagesimage_url, end_image_url, prompt
lipsyncSync face to audioimage_url, audio_url
Set mode explicitly, or omit it and the API infers the mode from the inputs you provide.

​
Iteration

Each primitive is independent. Redo any step without rerunning the whole pipeline:
  • Bad image? Regenerate with a different prompt or reference
  • Caption too long? Regenerate with length: "short"
  • Video glitchy? Analyze it, then regenerate with adjusted params
  • Clip too short? Use extend mode to continue it
  • Low quality? Upscale the image or video
  • Everything good but wrong caption? Just re-run the edit step

​
Content Agent (Slack Bot)

The Recoup Content Agent is a Slack bot that generates social-ready artist videos on @mention. It plugs into the content creation pipeline and delivers results directly in your Slack thread.

​
@Mention Syntax

@RecoupContentAgent <artist_account_id> [template] [batch=N] [lipsync]
ParameterRequiredDescription
artist_account_idYesUUID of the artist account
templateNoContent template name. Optional — when omitted, the pipeline runs with default settings. See GET /api/content/templates for options.
batch=NNoNumber of videos to generate (1-30, default 1)
lipsyncNoEnable lipsync mode (audio baked into video)

​
Examples

Basic — single video with default template: 
@RecoupContentAgent abc-123-uuid
Custom template: 
@RecoupContentAgent abc-123-uuid artist-caption-bedroom
Batch with lipsync: 
@RecoupContentAgent abc-123-uuid batch=3 lipsync

​
Architecture

ComponentLocationPurpose
Slack webhookPOST /api/content-agent/slackReceives @mention events
Callback endpointPOST /api/content-agent/callbackReceives polling results
Bot singletonlib/content-agent/bot.tsChat SDK with Slack adapter + Redis state
Mention handlerlib/content-agent/handlers/Parses args, validates artist, triggers pipeline
Poll taskpoll-content-run (Trigger.dev)Monitors content runs, posts results via callback

​
Data Flow

  1. Slack event → POST /api/content-agent/slack handles the webhook
  2. Mention handler parses the command, calls GET /api/content/validate to check artist readiness
  3. Content creation triggered via POST /api/content/create — returns runIds
  4. Poll task (poll-content-run) monitors the Trigger.dev runs every 30 seconds (up to 30 minutes)
  5. Callback → POST /api/content-agent/callback receives results and posts video URLs back to the Slack thread

​
Setup

​
1. Create a Slack App

  1. Go to api.slack.com/apps and create a new app
  2. Under OAuth & Permissions, add bot scopes:
    • chat:write — post messages
    • app_mentions:read — receive @mention events
  3. Under Event Subscriptions:
    • Enable events
    • Set the request URL to https://api.recoupable.com/api/content-agent/slack
    • Subscribe to app_mention bot event
  4. Install the app to your workspace

​
2. Configure Environment Variables

VariableWhereDescription
SLACK_CONTENT_BOT_TOKENAPI (Vercel)Bot OAuth token (xoxb-...) from Slack app
SLACK_CONTENT_SIGNING_SECRETAPI (Vercel)Signing secret from Slack app Basic Information
CONTENT_AGENT_CALLBACK_SECRETAPI + TasksShared secret for callback authentication (generate a random string)
RECOUP_API_KEYAPI + TasksRecoup API key for authenticating pipeline requests
RECOUP_API_BASE_URLTasks (Trigger.dev)API base URL (e.g., https://api.recoupable.com)

​
3. Verify

Mention the bot in any Slack channel where it’s been added: 
@RecoupContentAgent <your-artist-account-id>
You should see:
  1. An immediate acknowledgment message
  2. A video URL reply in the thread after ~5-10 minutes

​
Troubleshooting

IssueCauseFix
No response from botEvent subscription URL not configuredCheck Slack app Event Subscriptions
”Artist not found”Invalid artist_account_idVerify the UUID exists in the platform
”No GitHub repository found”Artist missing repo configEnsure the artist account has a linked GitHub repo
Timeout after 30 minPipeline took too longCheck Trigger.dev dashboard for the failed run
”Unsupported template”Invalid template nameUse GET /api/content/templates to list available templates