--- title: "Edit video from an AI agent with GPT-Video" description: "Give an AI agent the GPT-Video API or the MCP server. What to put in its context, which files it should read and how it should handle errors." url: "https://www.gpt-video.com/developers/ai-agents" --- # Use GPT-Video from an AI agent You can edit video from an AI agent with GPT-Video. The agent uploads a long video, asks GPT-Video for clips, and exports the ones you choose as MP4 files. This page shows two ways to connect an agent, a prompt to copy, and the rules an agent should follow so that it does not spend twice or retry a call that cannot succeed. ## REST API or MCP server An agent that can run code or send HTTP requests can use the REST API. Coding agents such as Claude Code, Codex and Cursor work this way. The REST API covers every step, including the upload of the video file, and it has an endpoint for each operation in the [API reference](/developers/api.md). An assistant that supports MCP connectors can use the [MCP server](/developers/mcp.md) instead. It comes in two editions. The directory edition has eight tools for Auto Clip, and you upload the video in the GPT-Video app. The full edition has the whole catalogue, uploads included, and you can pick the toolsets you need. MCP tool names and REST operation ids are different things. Five names exist in both, and they take different input. An agent that uses the REST API should read the REST names from the API manual and ignore the MCP tools. ## Give the agent a key Create an API key on the Developers page of the GPT-Video app, at `https://www.gpt-video.com/app/developers`. Give it to the agent in the environment variable `GPT_VIDEO_API_KEY`. Do not paste the key into the chat, because the chat history keeps it. The scopes of the key decide what the agent can do. A key with `clips:read` and `clips:write` can upload, create projects and read results, but it cannot start an analysis or an export. Add `spend` when you want the agent to use credits. [Authentication](/developers/authentication.md) explains each scope. ## The prompt to copy Paste this prompt into your agent, then add the video you want to use. ```text Use the GPT-Video API to cut my video into short vertical clips. First read https://www.gpt-video.com/developers/api.md and use only the endpoints and parameters it lists. My API key is in the environment variable GPT_VIDEO_API_KEY. Before you start an analysis, call estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) and tell me the price. If a call answers PLAN_REQUIRED, INSUFFICIENT_CREDITS or DAILY_LIMIT_REACHED, stop and tell me. Send an Idempotency-Key on every request that spends, and send the same key again when you retry it. Wait for jobs with GET /v1/jobs/{jobId}?wait=25. When the exports are done, download the files and tell me where you saved them. ``` ## The skill file Agents that load skills, such as Claude Code, can use [skill.md](/developers/skill.md). It holds the steps of a full run, the error codes after which the agent sends the same request again, changes the request, or stops and tells you, and the rules for the API bonus. Save it as `SKILL.md` in a folder named `gpt-video` inside the skills folder of your agent. ## Rules an agent should follow The [API manual](/developers/api.md) has these rules too, so an agent that reads it first knows them. - Do not assume endpoints have parameters other than the ones explicitly specified. An unknown parameter is refused with `UNKNOWN_PARAMETER`. - Decide by `error.code`, never by the HTTP status. A `429` can mean wait a minute or stop until tomorrow. - Create one `Idempotency-Key` for each request that spends, before you send it. If the request fails or times out, send it again with the same key. A new key is a new charge. - Wait for a job with `GET /v1/jobs/{jobId}?wait=25` until `job.status` is `done`, `failed` or `cancelled`. - Download `export.downloadUrl` without the `Authorization` header. The link expires, so save the file at once, and call `get_export` (`GET /v1/exports/{exportId}`) again for a new link. - When the error table says to tell the user, stop and tell the user. Sending the same request again does not change the answer. - When a `503` answer has `details.reason` set to `switched_off`, do not send the request again. The operation is turned off on this server. [Errors](/developers/errors.md) lists every code with the action an agent should take. ## The API bonus API bonus: 50 credits. No card needed. An account can get the API bonus the first time it uses the API. We give a limited number each day. If none are left, a call on another day can get it. To get it, the account needs a confirmed email address and a password, or a Google sign-in. Addresses from throwaway email services do not qualify. Each person gets it once. API bonus credits can be spent only through the API. They expire 30 days after you get them. After the bonus, the API needs a Creator or Studio plan. We can pause the API bonus. While it is paused, a call it would pay for answers PLAN_REQUIRED. The Developers page in the app shows whether you have the bonus, and why not if you do not. An agent can call `get_credits` (`GET /v1/credits`) to read `bonus.status` and `bonus.remaining` before it spends. When a call answers `PLAN_REQUIRED`, `INSUFFICIENT_CREDITS` or `DAILY_LIMIT_REACHED`, the agent should stop and tell you. To keep using the API after the bonus, you choose a Creator or Studio plan on [Pricing](/pricing). [API pricing](/developers/pricing.md) has the details. ## Try it step by step The [quickstart](/developers/quickstart.md) runs the same steps by hand, one call at a time. It helps you check your key and see what the agent will do before you hand it the work.