# AI

> An OpenAI-compatible gateway to every major lab's models, for chat, embeddings, images, video, speech and transcription, metered per call.

One metered entry point for language models, embeddings, images, video, text to speech and speech to text. It is **OpenAI-compatible** under `/v1/ai`, so the OpenAI SDK, the AI SDK (`@ai-sdk/openai`) and most agents work by changing the base URL. Pick a thelastapi model by what it is for (`vibiz/fast`, `vibiz/smart`, `vibiz/image`…), or any lab's model by its own id (`anthropic/claude-opus-5.5`, `moonshotai/kimi-k3.1-pro`…). Either way exactly that model runs: thelastapi never swaps in another one.

```ts
import OpenAI from 'openai';
const openai = new OpenAI({ baseURL: process.env.VIBIZ_AI_BASE_URL, apiKey: process.env.VIBIZ_AI_API_KEY });
const stream = await openai.chat.completions.create({ model: 'vibiz/fast', messages, stream: true });
```

## Keys

- **Account key** (`vz_sk_…`): agents and scripts. Add `X-Vibiz-Project: prj_…` to bill a project.
- **Project AI key** (`vz_ai_…`): `vibiz add ai`. The app's env gets `VIBIZ_AI_BASE_URL`, `VIBIZ_AI_API_KEY` and the aliases `OPENAI_BASE_URL`, `OPENAI_API_KEY`, so `new OpenAI()` works unchanged.
- **App key**: `new OpenAI(vibiz.ai)` with `@vibiz/app`.

## Models and pricing

A thelastapi model is a stable name for what it is for. Each runs **one** lab model, named below and in every answer (`served_model`); we move a tier to a newer model as labs ship them, and the change shows here. If that model is down, the call fails (`model_unavailable` or `provider_unavailable`) rather than run a different model you didn't pay for.

| thelastapi model | Runs on | For | Price (USD) |
| --- | --- | --- | --- |
| `vibiz/fast` (default chat) | GPT-6 Luna (OpenAI) | chat, tool calls, JSON | $0.10 / $0.50 per million tokens in / out |
| `vibiz/lite` | DeepSeek V4.1 Flash (DeepSeek) | the cheapest chat, 1M token context | $0.14 / $0.42 |
| `vibiz/smart-mini` | Claude Haiku 5.5 (Anthropic) | quick, strong writing and coding | $0.10 / $0.50 |
| `vibiz/balanced` | Gemini 3.8 Flash (Google) | quality and price balanced, 1M token context | $0.825 / $4.125 |
| `vibiz/reasoning` | GPT-6.1 Terra (OpenAI) | thinks before it answers: math, logic, planning | $1 / $5 |
| `vibiz/smart` | Claude Sonnet 5.5 (Anthropic) | hard tasks: writing, coding, agents | $2 / $10 |
| `vibiz/pro` | Claude Opus 5.5 (Anthropic) | the strongest chat tier, long agent runs | $4 / $20 |
| `vibiz/embed` | text-embedding-3-small (OpenAI) | embeddings, 1536 dimensions | $0.02 per million tokens |
| `vibiz/embed-large` | text-embedding-3-large (OpenAI) | embeddings, 3072 dimensions | $0.13 per million tokens |
| `vibiz/image` | Nano Banana 2 (Google) | fast images, edits, consistent characters | about $0.067 per image |
| `vibiz/image-pro` | Nano Banana 2.1 (Google) | Google's newest image model | about $0.034 per image |
| `vibiz/image-text` | GPT-5.4 Image 2 (OpenAI) | long prompts, text rendered in the image | about $0.04 per image |
| `vibiz/video` | LTX-2.5 Fast (Lightricks) | 6 s clips at 720p with sound, from a prompt or from an image (`image_url`), jobs only | $0.54 per video |
| `vibiz/voice` | Eleven v4 Turbo (ElevenLabs) | natural real-time voices | $0.04 per 1,000 characters |
| `vibiz/voice-pro` | Eleven v4 (ElevenLabs) | the most expressive voices | $0.08 per 1,000 characters |
| `vibiz/voice-lite` | Eleven Flash v2.5 (ElevenLabs) | the fastest voices, 32 languages | $0.04 per 1,000 characters |
| `vibiz/transcribe` | Scribe v2 (ElevenLabs) | speech to text, 99 languages | $0.22 per hour of audio |

These are the labs' list prices. A call is billed at what it really cost plus the AI fee in the price book (`markup_pct` on each model in `GET /v1/ai/models`). Some chat models charge more once a call's input passes a long-context threshold (`pricing.long_context`): GPT-6 models past 272,000 input tokens, Claude Haiku 5.5 past 100,000. Every JSON response carries `cost_micro_usd`, the exact cost of that call, and `served_model` (speech: the `X-Vibiz-Served-Model` header).

## All models

Beyond the thelastapi models, **every language model from every major lab** runs by its own id: OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Qwen, Mistral, Meta, MiniMax, Z.ai and more, over 400 in all, kept current as labs release them. Search them in the console (**AI models**), with `GET /v1/ai/models?all=1&q=kimi`, `vibiz ai models kimi`, or the `vibiz_ai_models` tool.

```json
{ "model": "moonshotai/kimi-k3.1-pro", "messages": [{ "role": "user", "content": "Hi" }] }
```

It runs exactly that model, at its list price plus the AI fee, and the answer names it. Usage groups a model behind a thelastapi model under that thelastapi model, and any other model under its own id. The media models above (`google/gemini-nano-banana-2.1`, `elevenlabs/v4`…) and older ones (`black-forest-labs/flux-schnell`, `openai/whisper-1`…) are called by id the same way. A model that isn't in the list can't be called (`invalid_request`, `param: "model"`), so a typo can't reach an expensive model.

Video takes `16:9` or `9:16` (`1:1` comes back as `16:9`).

## Limits

| | |
| --- | --- |
| Daily spend ceiling | $5 per account per UTC day by default (AI and actions together; an owner raises it in Billing); each call is held at its worst case before it runs |
| Credits | each call's worst case must fit in the account's balance (plus $0.50); out of credits: `402 payment_required` ([Billing](https://thelastapi.dev/docs/billing)) |
| Project budget | $1 per project per UTC day by default; the owner changes it in the console ▸ project ▸ AI ▸ Daily AI budget or `PATCH /v1/projects/:id/ai { daily_budget_usd, end_user_daily_budget_usd }` (`null`: none). Past it: `429`, `details.reason: "project_budget"`, `raise_url` |
| Alerts | the owners get an email at 80 % and 100 % of the daily spend limit and of each project's budget, and a banner on Overview and Usage, with a link that raises it ([Usage ▸ Limit alerts](https://thelastapi.dev/docs/usage#limit-alerts)) |
| `max_tokens` | 1,024 when not given, at most 16,384 (per model) |
| Images | 4 per request, 256–2,048 px a side |
| Speech | 4,096 characters |
| Transcription | 25 MB upload |
| Embeddings | 2,048 inputs |
| Rate, account key | 300 requests and 400k tokens a minute, 50 in flight |
| Rate, project key | 120 requests and 200k tokens a minute (settable to 600 and 2M), 25 in flight (up to 50) |
| Over the in-flight limit | the call waits for a free slot, first come first served, up to 60 s (it stops waiting if the caller disconnects), so a batch of images all goes through as slots free up; only after that wait is it `429`, `details.reason: "concurrency"` |
| Media links | permanent with a project ([Files](https://thelastapi.dev/docs/files)); 24 hours without one |

Building an app on AI: tell the owner the project budget and the account's daily spend limit it runs under and what you expect it to cost a day, and set `daily_budget_usd` to fit the expected traffic. A cap the app adds itself stays under these and tells the owner when it is hit: an app must never stop silently.

## Use it

```bash
curl https://thelastapi.dev/v1/ai/chat/completions \
  -H "Authorization: Bearer $VIBIZ_API_KEY" -H 'content-type: application/json' \
  -d '{"model":"vibiz/fast","messages":[{"role":"user","content":"Name a bakery in three words."}]}'
```

```bash
vibiz ai "Name a bakery in three words."
vibiz image "a croissant on a marble table" -o hero.png
vibiz say "Welcome to Acme Bakery" -o welcome.mp3 --voice alloy
vibiz transcribe call.m4a --language en
```

Agents use `vibiz_ai_chat`, `vibiz_image_generate`, `vibiz_speech_create` and `vibiz_speech_transcribe`; media comes back as links, never base64; with a project the link is permanent and the file is in the project's Files (`vibiz_files`). The same as actions: `POST /v1/actions/ai.chat { "input": { "prompt": "…" } }`.

| Route | Does |
| --- | --- |
| `POST /v1/ai/chat/completions` | chat, streaming (SSE) or not; tools, JSON mode |
| `POST /v1/ai/embeddings` | embeddings |
| `POST /v1/ai/images/generations` | images: `b64_json` (default) or `url` |
| `POST /v1/ai/audio/speech` | text to speech, streamed `mp3` or `pcm` |
| `POST /v1/ai/audio/transcriptions` | speech to text, multipart `file` |
| `POST /v1/ai/jobs`, `GET /v1/ai/jobs/:id` | slow images and video: `202`, then poll. Video: `{ "type": "video", "model": "vibiz/video", "input": { "prompt": "…", "image_url": "https://…" (optional: animate this still), "aspect_ratio": "16:9" \| "9:16" } }`. From an agent: `vibiz_video_generate`; from a terminal: `vibiz video "<prompt>" -o out.mp4 [--from-image <url>]` |
| `GET /v1/ai/models`, `GET /v1/ai/health` | catalogue with prices; per capability `ok`/`degraded`/`down` |

Voices are `alloy`, `ash`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`. Pass your own user's id as `user` (or `X-Vibiz-User`) and spend breaks down per end user.

## Generated media is kept in Files

Every image, video and audio you generate is saved in the project's [Files](https://thelastapi.dev/docs/files), with the model, the prompt and the cost. Use the `url` in the response (it is permanent), or `vibiz files latest` / `vibiz files search "<prompt words>"` later.

Files are named by date and prompt (`2026-10-28-cold-email-cover.png`). A call with a development key (the development app key or AI key) saves to the development Files; every other project call saves to production. A call billed to the account with no project has no Files to go to: it is not saved and its links expire after 24 hours. Saving never fails the call: if it can't be saved, you get the 24-hour link and no file fields.

The answers keep their OpenAI shape and add:

| Call | Added |
| --- | --- |
| `POST /v1/ai/images/generations` | `file_id` and `file_url` on each `data[i]`; with `response_format: "url"`, `url` is the permanent link |
| `POST /v1/ai/jobs` (image and video), once done | `file_id` and `file_url` on each `output.data[i]`; `url` is permanent and `expires_at` is `null` |
| `POST /v1/ai/audio/speech` | headers `X-Vibiz-File-Id` and `X-Vibiz-File-Url` (the file appears once the audio has finished) |
| actions `image.generate`, `speech.create` | `url` permanent, plus `file_id` and `file_url` |

## Your own keys

Have Google Cloud credits, or a Google account you'd rather pay? Add your own Google key and **Google's models** run on **your** Google account: Google bills you, and the call costs **0** on thelastapi (each answer says `"paid_by": "your_key"`, with `would_cost_micro_usd`: what it would have cost here). Models from other labs keep running on thelastapi, billed as usual: your key never moves a thelastapi model to a Gemini model.

Two kinds of Google credentials:

| Type | What it is | Serves |
| --- | --- | --- |
| `"gemini_api_key"` | a Gemini API key from Google AI Studio | Google's chat, image, video, speech and transcription models, and embeddings if you turn them on |
| `"vertex"` | a Google Cloud service account key file, a project id and a region (default `global`): Vertex AI, which spends Google Cloud credits | Gemini 3.1 Flash Lite, 3.5 Flash Lite and 3.5 Flash chat, and transcription, today; the rest stays on thelastapi |

```bash
GEMINI_API_KEY=… vibiz ai keys set google          # or type it at the hidden prompt
vibiz ai keys set google --vertex sa.json --region us-central1
vibiz ai keys                                       # status, and which models run on your key
vibiz ai keys test google
vibiz ai keys remove google
```

Or in the console: **API keys ▸ Your AI keys**. With the API: `PUT /v1/ai-keys/google` `{ "type": "gemini_api_key", "api_key": "…" }` (full-access keys only). A key is checked with a free call to Google before it is saved, and refused with the reason if Google refuses it. It is stored encrypted and never shown again: only its last 4 characters, when it was last used and its last error. A project can have its own key (`/v1/projects/:id/ai-keys/google`), which replaces the account's for that project.

What to know:

- **No silent fallback.** A call your key can serve runs only on your key. If Google refuses it or is down, the call fails (`provider_failed`, `details.reason: "customer_key_rejected"`, or `provider_unavailable`): it is never retried on thelastapi's account, so you are never billed by us by surprise.
- **What runs on your key**: any `google/…` model by its id (`google/gemini-4-argon`, `google/gemini-3.8-flash-tts`, `google/gemini-omni-1.1-flash`, `google/gemini-embedding-2`…), and the thelastapi models whose model is Google's: `vibiz/balanced` (Gemini 3.8 Flash), `vibiz/image` (Nano Banana 2) and `vibiz/image-pro` (Nano Banana 2.1).
- **Everything else runs on thelastapi**, billed as usual: the key's status lists every thelastapi model with `paid_by: "your_key"` or `"vibiz"`.
- **Embeddings are off by default** (`use_for`): vectors from another model don't match the ones your index already holds, and nothing would error. Turn them on for a new index: `PATCH /v1/ai-keys/google { "use_for": ["llm", "embeddings", …] }`.
- **Speech on your Google key comes back as WAV** (`audio/wav`) when you ask for `mp3`: we don't convert audio. `pcm` is the same 24 kHz 16-bit mono PCM as always.
- **Transcription on your Google key** takes files up to 14 MB, and video takes `16:9` or `9:16`.
- A job made on your key fails if you remove the key before it runs; it never runs on ours.

### Your own fal key

Add your own fal key and images and video run on **your** fal account: your fal balance pays, and the call costs **0** on thelastapi. Your key also runs **any fal endpoint** by its id.

```bash
vibiz ai keys add fal                       # hidden prompt; or FAL_KEY=… / --key-file key.txt
vibiz ai keys test fal
vibiz ai keys remove fal
```

Get the key at [fal.ai/dashboard/keys](https://fal.ai/dashboard/keys) (it looks like `key-id:secret`), or add it in the console: **API keys ▸ Your AI keys ▸ Add your fal key**. With the API: `PUT /v1/ai-keys/fal` `{ "type": "fal_key", "api_key": "…" }`. It is checked with a free call to your fal account first (nothing is generated) and refused with the reason if the key is wrong. A project can have its own (`/v1/projects/:id/ai-keys/fal`).

- **What runs on it**: `vibiz/video`, the Flux image models by id (`black-forest-labs/flux-schnell`, `black-forest-labs/flux-dev`), and any image or video model by its id (below). The key's status lists every thelastapi model with `paid_by`.
- **Edit a photo** (start from one or more photos): add `image_url` (one public https link, a Files link works) or `image_urls` (up to 8, to combine a person and a product, a face and an outfit) to `POST /v1/ai/images/generations`; the prompt says what to change. Works with `vibiz/image`, `vibiz/image-pro` (Nano Banana) and `vibiz/image-text`; a model that only draws from a prompt answers `400` with `details.reason: "model_takes_no_photo"` rather than ignoring the photo. Image jobs take the same fields inside `input`. MCP: `vibiz_image_generate { prompt, image_url }`; CLI: `vibiz image "make the background a beach" -o out.png --from-image <url>`.
  ```ts
  await openai.images.generate({ model: 'vibiz/image', prompt: 'make the background a beach', image_url: 'https://…/me.jpg' } as never);
  ```
- **Any image or video model by its id, on credit**: not only the thelastapi models. Find one with `GET /v1/ai/media-models?q=kling` (SDK `vibiz.ai.mediaModels({ q })`, MCP `vibiz_media_models`, CLI `vibiz media-models kling`): Kling, Seedance, Veo, Hailuo, Wan, face swap, lip sync, upscalers, background removal, try-on… each with its live price (unit: image, megapixel, video or seconds). Run it with `model: "<id>"` on `POST /v1/ai/images/generations` (images) or `POST /v1/ai/jobs` (video and long renders), with the model's own parameters in `model_input` (images: top level; jobs: inside `input`), up to 16 KB. It is charged from credits at its live price (per second: the `duration` asked, 5 s when unsaid); one call is capped at $10 (`call_too_expensive`). An id no model has answers `400` `unknown_model`. With the account's own key for that route, it runs on that key instead (cost 0):
  ```ts
  await vibiz.ai.jobs.create({ type: 'video', model: 'kling-video/v2.1/master/image-to-video', input: { prompt: 'she smiles', image_url: 'https://…/face.png', model_input: { duration: '10' } } });
  await openai.images.generate({ model: 'easel-ai/advanced-face-swap', prompt: 'swap', model_input: { face_image_0: 'https://…/a.png', target_image: 'https://…/b.png' } } as never);
  ```
  The prompt and the safety checker stay ours, and only images and video come back. (`fal_input` still works as the older name of `model_input`.)
- **No fallback, costs 0**: a call your fal key serves never runs on thelastapi's account. If it fails, the call fails:

| What happened | Error | Fix |
| --- | --- | --- |
| Your fal key was refused (wrong, revoked) | `provider_failed`, `details.reason: "customer_key_rejected"`: "Your fal key was refused: replace it in API keys ▸ Your AI keys." | Copy a new key from fal.ai/dashboard/keys and replace it |
| your fal account is out of balance | `provider_failed`, `details.reason: "customer_key_out_of_credit"`: "Your fal account is out of credit: top up at fal.ai/dashboard/billing, then try again." | Top up at fal.ai/dashboard/billing |
| Your fal account is rate limited | `429 rate_limited` with `retry_after_seconds` | Wait that long |

  The key's status shows the last error (`last_error`) until a call succeeds or **Test** passes.

## What agents can and can't do

Agents may call every AI route and tool; each call is metered and held against the daily ceiling. Rotating the project's production AI key is an owner's (`POST /v1/projects/:id/ai/keys/rotate`), and so are setting and removing your own provider keys; agents can read their status (`vibiz_ai_keys`), never a secret.

## Errors

OpenAI-shaped, so OpenAI SDKs read them: `{ "error": { "code", "message", "type", "param", "details"? } }`.

| Code | Status | When | Next step |
| --- | --- | --- | --- |
| `invalid_request` | 400 | bad input, unknown model, a cap exceeded; `param` names the field | fix the field |
| `content_filtered` | 400 | a content filter refused the request | change the prompt |
| `context_length_exceeded` | 400 | the input is longer than the model's window | shorten it |
| `payload_too_large` | 413 | body or upload over its cap | send less |
| `unauthorized` | 401 | missing, invalid or revoked key | check the key |
| `rate_limited` | 429 | `details.reason`: `daily_spend`, `project_budget`, `end_user_budget`, `requests_per_minute`, `tokens_per_minute`, `concurrency` | wait (`Retry-After`), or raise the budget; `daily_spend` resets at midnight UTC |
| `provider_unavailable` | 503 | every route failed; `details.reason` `timeout`, `stall`, `circuit_open` | retry later |
| `model_unavailable` | 503 | no route can run that model right now; thelastapi never swaps in another | retry after `details.retry_after_seconds`, or pick another model |
| `not_configured` | 503 | this model can't be served right now | use another thelastapi model |

Mid-stream, the error arrives as a final SSE event, `data: {"error": {…}}`, without `[DONE]`.
