AI agentsMarkdown
Use VidLab from your coding agent
Give Claude Code, Codex, Cursor or any agent that runs commands the VidLab skill and your API key, and it can find a model, read its options, price the job, upload your files, run it and save the result, all through the VidLab API. One command installs the skill:
npx skills add https://vidlab.aiSet your key first. The skill reads it from the VIDLAB_API_KEY environment variable, never from the chat. Create a key on API keys.
What the skill does
The skill is one Markdown file, SKILL.md, that your agent reads when you ask for images, video or audio. It tells the agent how to:
- find a model in the live model list, and read the exact options it takes;
- price the job first (free) and tell you the price before anything is spent;
- upload your local files, start the job with a price cap and an idempotency key, and poll it;
- download the result, and read every error code and what to do about it.
It also walks an agent through adding VidLab to your app: a small server-side client, your existing generation calls switched over, and one priced test call.
Which do I need
| You want to | Use | Ask your agent, for example |
|---|---|---|
| Make an image, a video or a voice-over now | The skill | "Make a 5 second 9:16 video of a perfume bottle on wet stone with VidLab. Tell me the price first." |
| Add VidLab to your app, or move its generation calls over | The skill | "Add VidLab to this app and switch our image generation to it." |
| Run a ready-made ad format | The skill | "Make a 15 second talking head ad for my sleep gummies with VidLab." |
| Scripts and CI, no agent | The CLI | vidlab run gpt-image-2 --prompt "a red sneaker" --wait --out sneaker.webp |
| Give an agent the whole reference | llms.txt | "Read https://vidlab.ai/vidlab-api/llms.txt, then call the VidLab API for me." |
Quick start
- Create a key on API keys and add credit on Billing. Keys start with
vidlab_sk_and are shown once. - Put the key in your environment, then open a new terminal so it is read. On macOS and Linux add this line to
~/.zshrc(or~/.bashrc) in a text editor. On Windows run the PowerShell line: it asks for the key, so it never lands in your command history.
export VIDLAB_API_KEY="vidlab_sk_your_key_here"[Environment]::SetEnvironmentVariable("VIDLAB_API_KEY", (Read-Host "VidLab API key"), "User")- Install the skill from your project folder (add
-gto install it for every project):
npx skills add https://vidlab.ai- Start your agent from that new terminal and ask. Begin with a free question: "Use VidLab to list three video models and the price of a 5 second clip at 720p."
What happens when you ask
| Step | What the agent does | The call |
|---|---|---|
| FIND | Searches the live model list for the task. | GET /v1/models?kind=video&search=... |
| READ | Reads the model's params: the only fields, values and ranges it takes. | GET /v1/models/{id} |
| UPLOAD | Sends your local files and gets a link for each (kept 7 days). | POST /v1/uploads |
| RUN | Prices the exact request, tells you the price, then submits with a cap and an Idempotency-Key and polls until it ends. | POST /v1/generations/quote, POST /v1/generations, GET /v1/generations/{id} |
| SAVE | Downloads the file. Output links last 6 hours; the files are kept 30 days. | GET /v1/generations/{id}/content |
Good to know
- Model ids come from the live list (
GET /v1/models). The agent never makes one up; if a name you give is not there, it shows you the closest ones. - Auth is always
Authorization: Bearer $VIDLAB_API_KEY, againsthttps://vidlab.ai/v1. - Your agent's jobs are billed exactly like your own API calls, from your prepaid balance and only when they succeed. They show in Task logs and Usage logs.
- Keep the key in the environment: never in the chat, a screenshot, a prompt or a repository. If it ever leaks, revoke it on API keys and make a new one.
Next: Install the VidLab skill, What your agent can do, Troubleshooting.