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/api. Store it as an environment variable:

export VIDEOGEN_API_KEY="sk_videogen_live_..."
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

The fastest way to give an agent VideoGen is the MCP server. Point Cursor, Claude, or any MCP client at the hosted endpoint. For a custom agent in code, install @videogen/sdk or videogen and bind a function that starts a workflow, as in the examples below.

Automating with no code? Use the n8n community node (n8n-nodes-videogen) or the Pipedream components to start VideoGen workflows and wait for the exported MP4. Prefer ChatGPT or Postman? See ChatGPT (custom GPT) and Postman.

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, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.",
        },
        quality="HIGH",
        auto_export=True,
        remix_actions=[
            {"type": "ENABLE_CAPTIONS"},
            {
                "type": "CONVERT_IMAGES_TO_VIDEOS",
                "motion_prompt": "slow cinematic push-in",
                "mute_output_videos": True,
                "quality": "HIGH",
            },
        ],
    )
    run = poll_workflow_run(client, response["workflowRunId"])
    return {"status": run["status"], "download_url": run.get("download_url") or run.get("downloadUrl")}
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, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.",
          },
          quality: "HIGH",
          autoExport: true,
          remixActions: [
            { type: "ENABLE_CAPTIONS" },
            {
              type: "CONVERT_IMAGES_TO_VIDEOS",
              motionPrompt: "slow cinematic push-in",
              muteOutputVideos: true,
              quality: "HIGH",
            },
          ],
        });
        const run = await pollWorkflowRun({ client: vg, workflowRunId });
        return { status: run.status, downloadUrl: run.downloadUrl };
      },
    }),
  },
  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, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.",
        },
        quality="HIGH",
        auto_export=True,
        remix_actions=[
            {"type": "ENABLE_CAPTIONS"},
            {
                "type": "CONVERT_IMAGES_TO_VIDEOS",
                "motion_prompt": "slow cinematic push-in",
                "mute_output_videos": True,
                "quality": "HIGH",
            },
        ],
    )
    run = poll_workflow_run(client, response["workflowRunId"])
    return {"status": run["status"], "download_url": run.get("download_url") or run.get("downloadUrl")}

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.

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

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.