Quickstart
Add credits, create an API key, then send a request to any supported model.
Add creditsDirect link to Add credits
Gateway uses prepaid credit, so add credits before your first request. Without credit, requests return 402.
- Sign in at projects.mastra.ai.
- Open Billing in your organization and add credits.
Optionally turn on auto top-up so requests don't fail when your balance runs low.
Create an API keyDirect link to Create an API key
- Open Gateway > API keys and select Create key.
- Copy the key. It starts with
msk-gateway-and is shown only once.
Store the key in an environment variable:
.env
MASTRA_GATEWAY_API_KEY="msk-gateway-..."
Send a requestDirect link to Send a request
- cURL
- TypeScript
- Python
curl https://gateway-api.mastra.ai/v1/chat/completions \
-H "Authorization: Bearer $MASTRA_GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-6.1-sol",
"messages": [{ "role": "user", "content": "Say hello in one word." }]
}'
src/index.ts
import OpenAI from 'openai'
const client = new OpenAI({
apiKey: process.env.MASTRA_GATEWAY_API_KEY,
baseURL: 'https://gateway-api.mastra.ai/v1',
})
const completion = await client.chat.completions.create({
model: 'openai/gpt-6.1-sol',
messages: [{ role: 'user', content: 'Say hello in one word.' }],
})
console.log(completion.choices[0].message.content)
main.py
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MASTRA_GATEWAY_API_KEY"],
base_url="https://gateway-api.mastra.ai/v1",
)
completion = client.chat.completions.create(
model="openai/gpt-6.1-sol",
messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(completion.choices[0].message.content)
Change the model value to call another provider, for example anthropic/claude-sonnet-5.5. Find more models in the model catalog, or list them with GET /v1/models.
The response includes an x-request-id header. Use it to find the request in your usage logs.
Use Gateway from a Mastra agentDirect link to Use Gateway from a Mastra agent
Set MASTRA_GATEWAY_API_KEY, then use a model ID with the mastra/ prefix:
src/mastra/agents/assistant.ts
import { Agent } from '@mastra/core/agent'
export const assistant = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant.',
model: 'mastra/openai/gpt-6.1-sol',
})
Next stepsDirect link to Next steps
- Integrations: AI SDK, Anthropic SDK, LangGraph, Pydantic AI, and more
- Keys and BYOK: Restrict keys and use your own provider accounts
- Models and routing: How Gateway picks a provider