AI Gateway
For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.
The Convex AI Gateway is a managed service that lets your app call AI models from actions. Convex holds the provider credentials, so you don't need to obtain, store, or rotate a key. Your action authenticates with a short-lived token scoped to your deployment.
const { text } = await generateText({
model: convexGateway("anthropic/claude-sonnet-4.5"),
prompt,
});
See Getting started for the full setup.
Supported endpoints
Text generation
See Getting started for text generation and embedding examples.
| Endpoint | What it does |
|---|---|
GET /v1/models | List available models |
POST /v1/chat/completions | Chat completions, streaming and non-streaming |
POST /v1/embeddings | Generate embeddings |
POST /v1/messages | Anthropic Messages, streaming and non-streaming |
POST /v1/responses | OpenAI Responses, streaming and non-streaming |
Decisions with Jev
Call /alpha/decisions to classify or score data with Jev. See
Decisions for the request format.
The /alpha/decisions request and response format may change during alpha.
Images and videos
| Endpoint | What it does |
|---|---|
POST /v1/images/generations | Generate images |
POST /v1/videos/generations | Wait for a video and download it |
POST /v1/videos | Start an async video job |
POST /v1/videos/status | Check an async job |
POST /v1/videos/download | Download a completed async video |
See Images and videos for SDK examples and async availability requirements.
The request and response format may change during alpha.
Speech and transcription
| Endpoint | What it does |
|---|---|
POST /v1/audio/transcriptions | Transcribe audio |
POST /v1/audio/speech | Generate spoken audio |
See Voice for SDK examples and for audio chat models.
The request and response format may change during alpha.
See HTTP API for the request and response shapes.
Who can use it
The AI Gateway is available to teams on a paid plan. It works on Convex Cloud production and development deployments, and on local deployments linked to a Convex project.
If your team or deployment can't use the gateway, getting a token fails with one of these errors:
| Situation | Error | What to do |
|---|---|---|
| Free plan, or gateway disabled for the team | AiGatewayDisabled | Upgrade, or email support@convex.dev if this looks wrong |
| Anonymous or outdated local deployment | AiGatewayUnavailable | Log in, update the Convex CLI, then restart npx convex dev and accept the backend upgrade if prompted |
| Self-hosted deployment | AiGatewayUnavailable | Call the provider with your own key, stored as an environment variable |
| Local deployment of a team over its spending limit | SpendingLimitExceeded | Raise the limit in the dashboard, or wait for it to reset |
| Local deployment of a suspended team | TeamSuspended | Email support@convex.dev |
Calls made with a deploy key, or by a dashboard member, also need a role that allows the AI Gateway. End users of your app need no extra permission.
Without the gateway
If you don't want to use the AI Gateway, store your provider API key as an environment variable and call the provider SDK from an action.