Video Generator
Generate educational video
Create a new educational video generation job. **Modes:** - `async`: Fire and forget. Returns immediately with runId. Poll status endpoint to track progress. - `sync`: Waits for video generation to complete before returning. May take 8-15 minutes. **Webhook Support (async mode - optional):** Provide a `webhookUrl` to receive ONE notification when generation completes or fails. Use status polling (`GET /status/:runId`) for real-time progress updates during generation.
OpenAPI specificationPOST
/api/v1/video-generator/createAuthentication
x-api-key
Request
curl --globoff --request POST \
--url 'https://api.example.com/api/v1/video-generator/create' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"topic": "The American Revolution"
}'Replace credential and <field> placeholders with your own values. URL placeholders appear as %3Cfield%3E. Review the example values before sending your request.
Replace https://api.example.com with the API server URL.
Use the sample JSON body as your starting point, and enter values that match the endpoint's schema.
Request body schema or example
{
"type": "object",
"properties": {
"topic": {
"type": "string",
"description": "Topic for the educational video",
"example": "The American Revolution"
},
"length": {
"type": "number",
"description": "Video length in seconds (must be multiple of 8, default: 120)",
"example": 120,
"minimum": 8,
"maximum": 320
},
"aspectRatio": {
"type": "string",
"description": "Aspect ratio for the video",
"enum": [
"16:9",
"9:16"
],
"default": "16:9"
},
"veoModel": {
"type": "string",
"description": "Video generation model (fast for quicker results, standard for best quality)",
"enum": [
"veo-3.1-generate-001",
"veo-3.1-generate-preview",
"veo-3.1-fast-generate-preview"
],
"default": "veo-3.1-fast-generate-preview"
},
"educationLevel": {
"type": "string",
"description": "Target education level",
"example": "high school level",
"default": "high school level"
},
"language": {
"type": "string",
"description": "Language for the video dialogue. Accepts language codes (e.g., \"en\", \"es\", \"fr\", \"de\", \"zh\", \"ja\", \"ko\") or full names (e.g., \"English\", \"Spanish\")",
"example": "es",
"default": "en"
},
"continuityMode": {
"type": "string",
"description": "Continuity mode for frame generation",
"enum": [
"scene-by-scene",
"continuous-flow"
],
"default": "continuous-flow"
},
"enableSpeechBubbles": {
"type": "boolean",
"description": "Enable speech bubbles with character tracking",
"default": true
},
"visualStyle": {
"type": "string",
"description": "Visual style for the video (art/aesthetic style)",
"example": "bright colorful educational animation with cartoon characters"
},
"visualStyleReferenceUrl": {
"type": "string",
"description": "URL to a sample frame/image that defines the visual style. Used only for the first frame to establish the aesthetic.",
"example": "https://example.com/my-style-reference.png"
},
"visualStyleIncludesCharacters": {
"type": "boolean",
"description": "When true and visualStyleReferenceUrl is provided, skips including separate character reference images (use when your style reference already contains the characters)",
"default": false
},
"narrativeStyle": {
"type": "string",
"description": "Narrative style for the video (storytelling/teaching approach). Defaults to visualStyle if not provided.",
"example": "engaging educational conversation, story-driven narrative, Q&A format"
},
"additionalPrompt": {
"type": "string",
"description": "Additional context or instructions for script generation",
"example": "Focus on key battles and important figures. Make it exciting!"
},
"customOutline": {
"type": "string",
"description": "Custom outline/script structure. When provided, skips AI outline generation and uses this outline exactly. The AI will follow your structure 100% when generating the detailed script.",
"example": "Scene 1: Introduction to photosynthesis - explain what it is and why it matters\nScene 2: The role of sunlight - explain how plants capture light energy\nScene 3: Water and CO2 - explain the inputs plants need\n..."
},
"mainCharacter": {
"description": "Custom main character (defaults to Sparky)",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Character ID"
},
"name": {
"type": "string",
"description": "Character name"
},
"role": {
"type": "string",
"description": "Character role"
},
"description": {
"type": "string",
"description": "Character description"
}
},
"required": [
"id",
"name",
"role"
]
}
]
},
"secondaryCharacter": {
"description": "Custom secondary character (defaults to Tiger)",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Character ID"
},
"name": {
"type": "string",
"description": "Character name"
},
"role": {
"type": "string",
"description": "Character role"
},
"description": {
"type": "string",
"description": "Character description"
}
},
"required": [
"id",
"name",
"role"
]
}
]
},
"mode": {
"type": "string",
"description": "Generation mode: async (returns immediately with webhook) or sync (waits for completion)",
"enum": [
"async",
"sync"
],
"default": "async"
},
"webhookUrl": {
"type": "string",
"description": "Webhook URL for async updates (only used in async mode)",
"example": "https://yourapp.com/webhooks/video-generation"
}
},
"required": [
"topic"
]
}Responses
201Video generation job created successfully
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"runId": {
"type": "string",
"example": "2025-11-15T12-30-45-abc123"
},
"status": {
"type": "string",
"enum": [
"pending",
"script_generation",
"frame_generation",
"video_prompt_generation",
"video_generation",
"video_stitching",
"completed",
"failed"
],
"example": "pending"
},
"mode": {
"type": "string",
"enum": [
"async",
"sync"
],
"example": "async"
},
"message": {
"type": "string",
"example": "Video generation started. Use /status/:runId to check progress."
},
"result": {
"type": "object",
"properties": {
"scriptUri": {
"type": "string"
},
"frameUris": {
"type": "array",
"items": {
"type": "string"
}
},
"videoUris": {
"type": "array",
"items": {
"type": "string"
}
},
"finalVideoUri": {
"type": "string"
},
"finalVideoSignedUrl": {
"type": "string"
},
"duration": {
"type": "number"
}
}
}
}
}