Use with AI agents

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.

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

Quick setup

$
npm install @videogen/sdk

$
export VIDEOGEN_API_KEY="sk_videogen_live_..."

Framework examples

OpenAI Agents SDK

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

Vercel AI SDK

1
import { VideoGen, pollWorkflowRun } from "@videogen/sdk";
2
import { openai } from "@ai-sdk/openai";
3
import { generateText, tool } from "ai";
4
import { z } from "zod";
5
6
const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });
7
8
const 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({ client: vg, workflowRunId });
28
      },
29
    }),
30
  },
31
  maxSteps: 5,
32
  prompt: "Make a short video explaining why staying hydrated matters",
33
});

LangChain

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

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
3
This 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
11
Endpoints are async and return status 202. Workflows return `{ workflowRunId, projectId, projectUrl }`;
12
poll `GET /v1/workflows/runs/{id}` or use `pollWorkflowRun`. Tools return `{ toolExecutionId }`;
13
poll `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-motion-graphic`: Generate an animated motion graphic (experimental)
35
- `POST /v1/tools/generate-avatar`: Create avatar videos
36
- `POST /v1/tools/vectorize-image`: Vectorize images to SVG
37
- `POST /v1/tools/remove-image-background`: Remove image backgrounds
38
- `POST /v1/tools/remove-video-background`: Remove video backgrounds
39
- `POST /v1/tools/upscale-image`: Upscale images
40
- `POST /v1/tools/upscale-video`: Upscale videos
41
- `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 an API server that lets AI clients actually run VideoGen (generate videos, images, voiceovers, and more). The API server is available as a hosted remote server (recommended) or a local server.

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 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.

Get a key from app.videogen.io/api. The server comes in two transports that expose the same tools.

Remote (recommended)

The hosted server needs nothing to install or update. Point your client at the endpoint and send your key as a bearer token:

1
{
2
  "mcpServers": {
3
    "videogen": {
4
      "url": "https://mcp.videogen.io/mcp",
5
      "headers": {
6
        "Authorization": "Bearer sk_videogen_live_..."
7
      }
8
    }
9
  }
10
}

The hosted server is stateless: your key is read from the request header, forwarded only to the VideoGen API, and never stored.

Local (stdio)

The local server runs as a subprocess launched with npx and reads your key from the VIDEOGEN_API_KEY environment variable:

1
{
2
  "mcpServers": {
3
    "videogen": {
4
      "command": "npx",
5
      "args": ["-y", "@videogen/mcp"],
6
      "env": {
7
        "VIDEOGEN_API_KEY": "sk_videogen_live_..."
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.

See the MCP server reference for the full list of 37 tools, their parameters, the composite wait/pollIntervalMs/timeoutMs controls, and the MCP-tool-to-REST-endpoint mapping.

Resources