GuidesBuild with VideoGen

Use with AI agents

Add VideoGen media generation to your AI agent or agentic workflow.

The VideoGen API works with any AI agent or framework that supports function calling. Give your agent the ability to turn a script into a finished video, plus generate standalone images, voiceovers, sound effects, and avatar clips on demand.

Use the VideoGen API skill to build and manage media generation from your AI coding assistant:

$npx skills add video-gen/skills --skill api

Quick setup

1

Install the SDK

$npm install @videogen/sdk
2

Set your API key

Get a key from app.videogen.io/developers. Store it as an environment variable:

$export VIDEOGEN_API_KEY="your_api_key"
3

Use it in your agent

The examples below show how to define a “generate a video from a script” tool for popular agent frameworks. The same pattern works for any VideoGen endpoint.

Framework examples

OpenAI Agents SDK

1import os
2from agents import Agent, Runner, function_tool
3from videogen import VideoGenApi, poll_workflow_run
4
5client = VideoGenApi(token=os.environ["VIDEOGEN_API_KEY"])
6
7@function_tool
8def generate_video(script: str) -> dict:
9    """Generate a narrated video from a script using VideoGen."""
10    response = client.workflows.add_visuals_narrations_and_captions_to_script(
11        script=script,
12        visual_style={
13            "type": "AI_IMAGE",
14            "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
15        },
16        quality="HIGH",
17        remix_actions=[
18            {"type": "ENABLE_CAPTIONS"},
19            {"type": "SET_BACKGROUND_MUSIC", "file_id": "vg_file_...", "volume": 0.25},
20        ],
21    )
22    run = poll_workflow_run(client, response.workflow_run_id)
23    return {"status": run.status, "project_url": run.project_url}
24
25agent = Agent(
26    name="Video Agent",
27    instructions="You generate videos from scripts using VideoGen when asked.",
28    tools=[generate_video],
29)

Vercel AI SDK

1import { VideoGenClient, pollWorkflowRun } from "@videogen/sdk";
2import { openai } from "@ai-sdk/openai";
3import { generateText, tool } from "ai";
4import { z } from "zod";
5
6const vg = new VideoGenClient({ token: process.env.VIDEOGEN_API_KEY! });
7
8const result = await generateText({
9  model: openai("gpt-4o"),
10  tools: {
11    generateVideo: tool({
12      description: "Generate a narrated video from a script using VideoGen",
13      parameters: z.object({ script: z.string() }),
14      execute: async ({ script }) => {
15        const { workflowRunId } = await vg.workflows.scriptToVideo({
16          script,
17          visualStyle: {
18            type: "AI_IMAGE",
19            aiStyle: "loose watercolor illustration with visible brushstrokes and soft color bleeds",
20          },
21          quality: "HIGH",
22          remixActions: [
23            { type: "ENABLE_CAPTIONS" },
24            { type: "SET_BACKGROUND_MUSIC", fileId: "vg_file_...", volume: 0.25 },
25          ],
26        });
27        return await pollWorkflowRun(vg, workflowRunId);
28      },
29    }),
30  },
31  maxSteps: 5,
32  prompt: "Make a short video explaining why staying hydrated matters",
33});

LangChain

1import os
2from langchain.tools import tool
3from videogen import VideoGenApi, poll_workflow_run
4
5client = VideoGenApi(token=os.environ["VIDEOGEN_API_KEY"])
6
7@tool
8def generate_video(script: str) -> dict:
9    """Generate a narrated video from a script using VideoGen."""
10    response = client.workflows.add_visuals_narrations_and_captions_to_script(
11        script=script,
12        visual_style={
13            "type": "AI_IMAGE",
14            "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
15        },
16        quality="HIGH",
17        remix_actions=[
18            {"type": "ENABLE_CAPTIONS"},
19            {"type": "SET_BACKGROUND_MUSIC", "file_id": "vg_file_...", "volume": 0.25},
20        ],
21    )
22    run = poll_workflow_run(client, response.workflow_run_id)
23    return {"status": run.status, "project_url": run.project_url}

AGENTS.md

If you’re using an AI coding assistant like Cursor, Windsurf, or Claude Code, you can add the following to your project’s AGENTS.md or .cursor/rules/ to give the agent context about VideoGen:

1## VideoGen API
2
3This project uses the VideoGen API for media generation.
4
5- Docs: https://docs.videogen.io
6- LLM-optimized docs: https://docs.videogen.io/llms.txt
7- OpenAPI spec: https://docs.videogen.io/openapi.json
8- Base URL: https://api.videogen.io/v1
9- Auth: Bearer token in Authorization header
10
11Endpoints are async and return status 202. Workflows return `{ workflowRunId, projectId, projectUrl }`;
12poll `GET /v1/workflows/runs/{id}` or use `pollWorkflowRun`. Tools return `{ toolExecutionId }`;
13poll `GET /v1/tools/executions/{id}` or use `pollExecutedTool`. Poll until status is
14`succeeded`, `failed`, or `cancelled`.
15
16### Workflows (end-to-end video, the primary surface)
17
18- `POST /v1/workflows/script-to-video`: Turn a topic or script into a narrated video
19- `POST /v1/workflows/voiceover-to-video`: Build a video from an uploaded voiceover
20- `POST /v1/workflows/slideshow-to-video`: Build a narrated video from a PDF or slideshow
21
22### Projects
23
24- `GET /v1/projects`: List projects (API-created by default; pass `includeUiProjects=true` to also include dashboard-created projects)
25- `POST /v1/projects/{projectId}/export`: Export a project as MP4
26
27### Tools (standalone media generation)
28
29- `POST /v1/tools/generate-image`: Generate images from text or image
30- `POST /v1/tools/generate-video-clip`: Generate video from text, image, or video
31- `POST /v1/tools/text-to-speech`: Convert text to speech
32- `POST /v1/tools/generate-sound-effect`: Generate sound effects
33- `POST /v1/tools/generate-music`: Generate music from a prompt
34- `POST /v1/tools/generate-avatar`: Create avatar videos
35- `POST /v1/tools/vectorize-image`: Vectorize images to SVG
36- `POST /v1/tools/remove-image-background`: Remove image backgrounds
37- `POST /v1/tools/remove-video-background`: Remove video backgrounds
38- `POST /v1/tools/upscale-image`: Upscale images
39- `POST /v1/tools/upscale-video`: Upscale videos
40- `POST /v1/tools/image-3d-effect`: Add 3D motion to a still image

MCP

VideoGen offers two MCP (Model Context Protocol) servers: a hosted documentation server that lets AI clients read the API docs, and a local API server that lets AI clients actually run VideoGen (generate videos, images, voiceovers, and more).

Documentation MCP

Your VideoGen docs site includes a hosted MCP server that AI clients can connect to directly. This lets tools like Cursor and Claude Desktop query the full API documentation in real time. It is read-only — it answers questions about the API but does not call it.

Server URL: https://docs.videogen.io/_mcp/server

To connect in Cursor, add this to your MCP configuration:

1{
2  "mcpServers": {
3    "videogen-docs": {
4      "url": "https://docs.videogen.io/_mcp/server"
5    }
6  }
7}

API MCP server

The API MCP server runs locally and executes real VideoGen API calls on your behalf, using your own API key. Point any MCP client at it and your agent can generate videos from scripts, produce images and voiceovers, upload files, export projects, and manage runs — every VideoGen endpoint is exposed as a tool. Long-running operations (workflows, media tools, exports) are handled by composite tools that start the operation and wait for the finished result by default.

The server communicates over stdio and reads your API key from the VIDEOGEN_API_KEY environment variable. Get a key from app.videogen.io/developers.

To connect in Cursor (or any MCP client), add this to your MCP configuration:

1{
2  "mcpServers": {
3    "videogen": {
4      "command": "npx",
5      "args": ["-y", "@videogen/mcp"],
6      "env": {
7        "VIDEOGEN_API_KEY": "your_api_key"
8      }
9    }
10  }
11}

Your key stays on your machine — it is passed directly to the local server process and never sent anywhere except the VideoGen API.

Resources

Getting started

Install an SDK and make your first request.

Handling async tasks

Polling and webhook patterns for tool executions.

REST API Reference

Full endpoint documentation.