Skip to main content

​
POST /api/generate

Submits a new video generation job to the queue. The job will be processed asynchronously by the worker process.

​
Request Body

​
videoSubject
string
required
The subject or topic of the video. This is used to generate the script and search for relevant footage.Example: "The history of artificial intelligence"
​
voice
string
default:"en_us_001"
The TikTok voice to use for narration. Available voices depend on the TikTok TTS API.Common options:
  • en_us_001 - US English (Female)
  • en_us_002 - US English (Male)
  • en_us_006 - US English (Male, Deep)
  • en_us_007 - US English (Female, Upbeat)
​
paragraphNumber
integer
default:"1"
Number of paragraphs to generate in the script. More paragraphs result in longer videos.Typical range: 1-5
​
customPrompt
string
Optional custom prompt to guide script generation. If provided, this overrides the default script generation logic.Example: "Create a dramatic script about Mars colonization"
​
aiModel
string
The Ollama model to use for script generation. If not specified, uses the default model from /api/models.Example: "llama3.1:8b"
​
threads
integer
default:"2"
Number of threads to use for video processing. Higher values may speed up rendering but use more CPU.
​
subtitlesPosition
string
default:"center"
Vertical position of subtitles in the video.Options:
  • top
  • center
  • bottom
​
color
string
default:"white"
Color of subtitle text.Common options: white, yellow, red, green, blue
​
useMusic
boolean
default:"false"
Whether to add background music to the video. Music files must be uploaded via /api/upload-songs first.
​
automateYoutubeUpload
boolean
default:"false"
Whether to automatically upload the generated video to YouTube after completion.Requires YouTube API credentials to be configured.

​
Response

​
status
string
Always "success" for successful job submission.
​
message
string
Human-readable message: "Video generation queued."
​
jobId
string
Unique identifier for the generation job. Use this to poll job status and retrieve events.Format: UUID v4 (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890")

​
Example Request

curl -X POST http://localhost:8080/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "videoSubject": "The benefits of meditation",
    "voice": "en_us_001",
    "paragraphNumber": 3,
    "subtitlesPosition": "center",
    "color": "yellow",
    "useMusic": true
  }'

​
Example Response

{
  "status": "success",
  "message": "Video generation queued.",
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Error Responses

​
Missing Required Field

{
  "status": "error",
  "message": "videoSubject is required."
}
HTTP Status: 400 Bad Request

​
Next Steps

After submitting a generation job:
  1. Use the returned jobId to poll job status: GET /api/jobs/:id
  2. Stream real-time progress events: GET /api/jobs/:id/events
  3. Cancel the job if needed: POST /api/jobs/:id/cancel

Build docs developers (and LLMs) love

Get started for freeTalk to us