Guides

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 generate images, videos, 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 image” 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_executed_tool
4
5client = VideoGenApi(token=os.environ["VIDEOGEN_API_KEY"])
6
7@function_tool
8def generate_image(prompt: str) -> dict:
9    """Generate an image from a text prompt using VideoGen."""
10    response = client.tools.generate_image(prompt=prompt)
11    execution = poll_executed_tool(client, response.tool_execution_id)
12    return {"status": execution.status, "file_id": execution.results[0].storage_file_id}
13
14agent = Agent(
15    name="Media Agent",
16    instructions="You generate images using VideoGen when asked.",
17    tools=[generate_image],
18)

Vercel AI SDK

1import { VideoGenClient, pollExecutedTool } 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    generateImage: tool({
12      description: "Generate an image from a text prompt using VideoGen",
13      parameters: z.object({ prompt: z.string() }),
14      execute: async ({ prompt }) => {
15        const { toolExecutionId } = await vg.tools.generateImage({ prompt });
16        return await pollExecutedTool(vg, toolExecutionId);
17      },
18    }),
19  },
20  maxSteps: 5,
21  prompt: "Generate an image of a mountain at sunrise",
22});

LangChain

1import os
2from langchain.tools import tool
3from videogen import VideoGenApi, poll_executed_tool
4
5client = VideoGenApi(token=os.environ["VIDEOGEN_API_KEY"])
6
7@tool
8def generate_image(prompt: str) -> dict:
9    """Generate an image from a text prompt using VideoGen."""
10    response = client.tools.generate_image(prompt=prompt)
11    execution = poll_executed_tool(client, response.tool_execution_id)
12    return {"status": execution.status, "file_id": execution.results[0].storage_file_id}

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
11All tool endpoints are async. POST returns `{ toolExecutionId }` with status 202.
12Poll `GET /v1/tools/executions/{id}` until status is `succeeded`, `failed`, or `cancelled`.
13Use `pollExecutedTool` helper from the SDK to simplify this.
14
15### Available tools
16
17- `POST /v1/tools/generate-image`: Generate images from text or image
18- `POST /v1/tools/generate-video-clip`: Generate video from text, image, or video
19- `POST /v1/tools/text-to-speech`: Convert text to speech
20- `POST /v1/tools/generate-sound-effect`: Generate sound effects
21- `POST /v1/tools/generate-avatar`: Create avatar videos
22- `POST /v1/tools/vectorize-image`: Vectorize images to SVG
23- `POST /v1/tools/remove-image-background`: Remove image backgrounds
24- `POST /v1/tools/remove-video-background`: Remove video backgrounds
25- `POST /v1/tools/upscale-image`: Upscale images
26- `POST /v1/tools/upscale-video`: Upscale videos

MCP

Your VideoGen docs site includes a hosted MCP (Model Context Protocol) server that AI clients can connect to directly. This lets tools like Cursor and Claude Desktop query the full API documentation in real time.

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}

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.