# 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](/vidlab-api/docs/quickstart). One command installs the skill:

```bash
npx skills add https://vidlab.ai
```

Set your key first. The skill reads it from the `VIDLAB_API_KEY` environment variable, never from the chat. Create a key on [API keys](https://vidlab.ai/vidlab-api/api-keys).

## What the skill does

The skill is one Markdown file, [`SKILL.md`](https://vidlab.ai/vidlab-api/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-api/docs/cli) | `vidlab run gpt-image-2 --prompt "a red sneaker" --wait --out sneaker.webp` |
| Give an agent the whole reference | [llms.txt](/vidlab-api/docs/llms-txt) | "Read https://vidlab.ai/vidlab-api/llms.txt, then call the VidLab API for me." |

## Quick start

1. **Create a key** on [API keys](https://vidlab.ai/vidlab-api/api-keys) and add credit on [Billing](https://vidlab.ai/vidlab-api/billing). Keys start with `vidlab_sk_` and are shown once.
2. **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.

```bash macOS / Linux
export VIDLAB_API_KEY="vidlab_sk_your_key_here"
```

```powershell Windows PowerShell
[Environment]::SetEnvironmentVariable("VIDLAB_API_KEY", (Read-Host "VidLab API key"), "User")
```

3. **Install the skill** from your project folder (add `-g` to install it for every project):

```bash
npx skills add https://vidlab.ai
```

4. **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`, against `https://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](https://vidlab.ai/vidlab-api/logs) and [Usage logs](https://vidlab.ai/vidlab-api/usage).
- 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](https://vidlab.ai/vidlab-api/api-keys) and make a new one.

Next: [Install the VidLab skill](/vidlab-api/docs/agent-skill), [What your agent can do](/vidlab-api/docs/agent-capabilities), [Troubleshooting](/vidlab-api/docs/agent-troubleshooting).