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

from agents import Agent, Runner, function_tool
from videogen import VideoGen, poll_workflow_run
client = VideoGen(api_key="sk_videogen_live_...")
@function_tool
def generate_video(script: str) -> dict:
    """Generate a narrated video from a script using VideoGen."""
    response = client.workflows.script_to_video(
        script=script,
        visual_style={
            "type": "AI_IMAGE",
            "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
        },
        quality="HIGH",
        remix_actions=[
            {"type": "ENABLE_CAPTIONS"},
            {"type": "SET_BACKGROUND_MUSIC", "file_id": "vg_file_...", "volume": 0.25},
        ],
    )
    run = poll_workflow_run(client, response["workflowRunId"])
    return {"status": run["status"], "project_url": run.get("projectUrl")}
agent = Agent(
    name="Video Agent",
    instructions="You generate videos from scripts using VideoGen when asked.",
    tools=[generate_video],
)

Vercel AI SDK

import { VideoGen, pollWorkflowRun } from "@videogen/sdk";
import { openai } from "@ai-sdk/openai";
import { generateText, tool } from "ai";
import { z } from "zod";
const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });
const result = await generateText({
  model: openai("gpt-4o"),
  tools: {
    generateVideo: tool({
      description: "Generate a narrated video from a script using VideoGen",
      parameters: z.object({ script: z.string() }),
      execute: async ({ script }) => {
        const { workflowRunId } = await vg.workflows.scriptToVideo({
          script,
          visualStyle: {
            type: "AI_IMAGE",
            aiStyle: "loose watercolor illustration with visible brushstrokes and soft color bleeds",
          },
          quality: "HIGH",
          remixActions: [
            { type: "ENABLE_CAPTIONS" },
            { type: "SET_BACKGROUND_MUSIC", fileId: "vg_file_...", volume: 0.25 },
          ],
        });
        return await pollWorkflowRun({ client: vg, workflowRunId });
      },
    }),
  },
  maxSteps: 5,
  prompt: "Make a short video explaining why staying hydrated matters",
});

LangChain

from langchain.tools import tool
from videogen import VideoGen, poll_workflow_run
client = VideoGen(api_key="sk_videogen_live_...")
@tool
def generate_video(script: str) -> dict:
    """Generate a narrated video from a script using VideoGen."""
    response = client.workflows.script_to_video(
        script=script,
        visual_style={
            "type": "AI_IMAGE",
            "ai_style": "loose watercolor illustration with visible brushstrokes and soft color bleeds",
        },
        quality="HIGH",
        remix_actions=[
            {"type": "ENABLE_CAPTIONS"},
            {"type": "SET_BACKGROUND_MUSIC", "file_id": "vg_file_...", "volume": 0.25},
        ],
    )
    run = poll_workflow_run(client, response["workflowRunId"])
    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:

## VideoGen API
This project uses the VideoGen API for media generation.
- Docs: https://docs.videogen.io
- LLM-optimized docs: https://docs.videogen.io/llms.txt
- OpenAPI spec: https://docs.videogen.io/openapi.json
- Base URL: https://api.videogen.io/v1
- Auth: Bearer token in Authorization header
Endpoints are async and return status 202. Workflows return `{ workflowRunId, projectId, projectUrl }`;
poll `GET /v1/workflows/runs/{id}` or use `pollWorkflowRun`. Tools return `{ toolExecutionId }`;
poll `GET /v1/tools/executions/{id}` or use `pollExecutedTool`. Poll until status is
`succeeded`, `failed`, or `cancelled`.
### Workflows (end-to-end video, the primary surface)
- `POST /v1/workflows/script-to-video`: Turn a topic or script into a narrated video
- `POST /v1/workflows/voiceover-to-video`: Build a video from an uploaded voiceover
- `POST /v1/workflows/slideshow-to-video`: Build a narrated video from a PDF or slideshow
### Projects
- `GET /v1/projects`: List projects (API-created by default; pass `includeUiProjects=true` to also include dashboard-created projects)
- `POST /v1/projects/{projectId}/export`: Export a project as MP4
### Tools (standalone media generation)
- `POST /v1/tools/generate-image`: Generate images from text or image
- `POST /v1/tools/generate-video-clip`: Generate video from text, image, or video
- `POST /v1/tools/text-to-speech`: Convert text to speech
- `POST /v1/tools/generate-sound-effect`: Generate sound effects
- `POST /v1/tools/generate-music`: Generate music from a prompt
- `POST /v1/tools/generate-motion-graphic`: Generate an animated motion graphic (experimental)
- `POST /v1/tools/generate-avatar`: Create avatar videos
- `POST /v1/tools/vectorize-image`: Vectorize images to SVG
- `POST /v1/tools/remove-image-background`: Remove image backgrounds
- `POST /v1/tools/remove-video-background`: Remove video backgrounds
- `POST /v1/tools/upscale-image`: Upscale images
- `POST /v1/tools/upscale-video`: Upscale videos
- `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:

{
  "mcpServers": {
    "videogen-docs": {
      "url": "https://docs.videogen.io/_mcp/server"
    }
  }
}

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:

{
  "mcpServers": {
    "videogen": {
      "url": "https://mcp.videogen.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_videogen_live_..."
      }
    }
  }
}

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:

{
  "mcpServers": {
    "videogen": {
      "command": "npx",
      "args": ["-y", "@videogen/mcp"],
      "env": {
        "VIDEOGEN_API_KEY": "sk_videogen_live_..."
      }
    }
  }
}

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