> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.videogen.io/use-with-ai-agents/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server. # Use with AI agents > How to use the VideoGen API with AI coding assistants, MCP clients, and agent frameworks. Bind the TypeScript or Python SDK, or connect the MCP server. 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. > **Tip** > > Use the [VideoGen API skill](https://github.com/video-gen/skills/tree/main/api) to build and manage media generation from your AI coding assistant: > > ```bash > npx skills add video-gen/skills --skill api > ``` This page explains how to connect the VideoGen API to AI agents. Tool endpoints are asynchronous: POST returns a toolExecutionId, poll GET /v1/tools/executions/\{id} until status is succeeded/failed/cancelled. Use the `pollExecutedTool` helper in the TypeScript and Python SDKs to simplify this. End-to-end video workflows (`POST /v1/workflows/*`) return a workflowRunId. Poll GET /v1/workflows/runs/\{workflowRunId} or use `pollWorkflowRun` / `poll_workflow_run`. The OpenAPI spec is at [https://docs.videogen.io/openapi.json](https://docs.videogen.io/openapi.json). ## Quick setup ### Install the SDK ```bash npm install @videogen/sdk # TypeScript pip install videogen # Python ``` ### Set your API key Get a key from [app.videogen.io/api](https://app.videogen.io/api). Store it as an environment variable: ```bash export VIDEOGEN_API_KEY="sk_videogen_live_..." ``` ### 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 > **Tip** > > The fastest way to give an agent VideoGen is the [MCP server](/libraries/mcp). 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](/libraries/n8n) (`n8n-nodes-videogen`) or the [Pipedream components](/libraries/pipedream) to start VideoGen workflows and wait for the exported MP4. Prefer ChatGPT or Postman? See [ChatGPT (custom GPT)](/libraries/chatgpt) and [Postman](/libraries/postman). The supported agent path is the MCP server (hosted remote or local `@videogen/mcp`). For a custom agent in code, install the TypeScript or Python SDK and bind a function that starts a workflow. For no-code automation, the `n8n-nodes-videogen` community node and the VideoGen Pipedream components start VideoGen workflows and wait until the exported MP4 is ready. To connect ChatGPT, build a custom GPT with GPT Actions pointing at the OpenAPI document (see /libraries/chatgpt). The examples below show the underlying pattern for any framework that supports function calling. ### OpenAI Agents SDK (Python) ```python 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 (TypeScript) ```typescript 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 (Python) ```python 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: ```markdown ## 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: ```json { "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](https://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: ```json { "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: ```json { "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](/libraries/mcp) 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](/getting-started): Install an SDK and make your first request. * [Handling async tasks](/handling-async-tasks): Polling and webhook patterns for tool executions. * [REST API Reference](/rest-api-reference): Full endpoint documentation. * [OpenAPI spec](https://docs.videogen.io/openapi.json): Machine-readable specification. > HTTP API with TypeScript and Python SDKs for generating image, video, and audio assets with VideoGen.