Quick start
- Sign in or create an account.
- Open API keys and create a key. Copy it straight away: it is shown only once.
- Send your first request:
curl BASE_URL/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "groq/openai/gpt-oss-120b", "messages": [{"role": "user", "content": "Hello"}]}'
from openai import OpenAI # pip install openai
client = OpenAI(base_url="BASE_URL/v1", api_key="YOUR_KEY")
reply = client.chat.completions.create(
model="groq/openai/gpt-oss-120b",
messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)
const res = await fetch("BASE_URL/v1/chat/completions", {
method: "POST",
headers: {"Authorization": "Bearer YOUR_KEY", "Content-Type": "application/json"},
body: JSON.stringify({
model: "groq/openai/gpt-oss-120b",
messages: [{role: "user", content: "Hello"}],
}),
});
const data = await res.json();
console.log(data.choices[0].message.content);
Authentication
Send your personal API key with every request, in the Authorization header:
Authorization: Bearer YOUR_KEY
The header X-API-Key: YOUR_KEY works too. Requests with your keys use your plan's messages and credits, just like the chat. You can have up to 10 keys. Delete a key on the API keys page if you stop using it or it may have leaked; it stops working at once.
Base URL for OpenAI-compatible clients: BASE_URL/v1
Models
List the models your plan includes:
curl BASE_URL/v1/models -H "Authorization: Bearer YOUR_KEY"
Model names start with the provider: groq/… for Groq and openrouter/… for OpenRouter, for example groq/openai/gpt-oss-120b. Names ignore case, and a trailing :latest (which Ollama apps add) is ignored. The first model in the list is the recommended default. The list changes when the providers add or retire models, so read it rather than hard-coding names.
Chat completions
POST /v1/chat/completions takes the OpenAI chat format and answers in it, as one JSON reply or, with "stream": true, as server-sent events.
Supported fields
| Field | Notes |
|---|---|
model, messages | Required. messages needs at least one message. |
stream, stream_options | Streaming as server-sent events. |
temperature, top_p, seed, stop, max_tokens, max_completion_tokens, presence_penalty, frequency_penalty, logit_bias, logprobs, top_logprobs, user | Passed to the model as usual. |
response_format | JSON mode and JSON schemas, where the model supports them. |
tools, tool_choice, parallel_tool_calls | Function tools only. Built-in tools (web search, code execution) are removed. |
reasoning_effort, reasoning_format, include_reasoning | Groq models. GPT-OSS takes low, medium or high; Qwen 3 takes none or default. |
reasoning, include_reasoning, top_k, min_p, repetition_penalty | OpenRouter models. |
Other fields are ignored. Reasoning models return their reasoning in message.reasoning (or delta.reasoning when streaming).
Streaming
from openai import OpenAI
client = OpenAI(base_url="BASE_URL/v1", api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="groq/openai/gpt-oss-120b",
messages=[{"role": "user", "content": "Write a haiku about the sea"}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Ollama-compatible API
Apps made for Ollama can use this site as their Ollama server: set the server address to BASE_URL and add your key as a bearer token, if the app allows it.
| Endpoint | What it does |
|---|---|
GET /api/tags | Your plan's models, in Ollama's format. |
POST /api/chat | Chat. Streams newline-delimited JSON unless "stream": false. |
POST /api/generate | Single prompt with an optional system prompt. |
GET /api/version, /api/ps | Answered for apps that check them. |
Supported options: temperature, top_p, seed, num_predict, stop, frequency_penalty, presence_penalty (and top_k on OpenRouter models). format takes "json" or a JSON schema, think takes true, false, "low", "medium" or "high", and user messages may carry base64 images for models that read images. Tools need the OpenAI-compatible endpoint.
curl BASE_URL/api/chat \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "groq/openai/gpt-oss-120b", "stream": false,
"messages": [{"role": "user", "content": "Hello"}]}'
Connect an app
In apps such as Chatbox, Jan, Msty, AnythingLLM, Open WebUI or VS Code with Continue, add a custom provider with these settings:
| Provider type | OpenAI compatible (also called "OpenAI API" or "Custom OpenAI") |
| Base URL / API host | BASE_URL/v1 |
| API key | One of your personal keys |
| Model | A name from /v1/models, such as groq/openai/gpt-oss-120b |
If an app adds /v1 itself, enter the address without it.
Limits and usage
- Messages. Every chat request (
/v1/chat/completions,/api/chat,/api/generate) counts as one message. Listing models is free. Your plan has a number of messages per day, which resets at 00:00 UTC. After that, credits are used, one per message. Your dashboard shows what is left. - Failed requests are not counted. When no answer is delivered because of an error, the message is given back. A request you cancel yourself still counts.
- Rate limits for API keys. At most 60 requests a minute and 2 requests running at the same time, per account.
- Model limits. The models run on the providers' free tiers, which have their own per-minute and per-day limits. When a model is busy you get HTTP 429 with the code
upstream_busy: wait a little, or choose another model. - Request size. Very large requests are refused with HTTP 413. Long conversations use more of the models' limits, so start a new conversation when you change topic.
Errors
Errors are JSON: {"code": "…", "error": "A message you can show to people"}. Check the code when there is one: it is stable, while the message may change.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | upstream_rejected | The model provider could not process the request (for example, too long for the model, or refused by moderation). |
| 401 | Missing or invalid API key, or the session has ended. | |
| 402 | daily_limit | Today's plan messages are used up and there are no credits left. |
| 403 | model_not_in_plan | The model is not included in your plan. |
| 404 | model_unavailable | Unknown model name. Read /v1/models. |
| 413 | request_too_large | The request is too long for the model's free limits. |
| 429 | rate_limited | More than 60 requests a minute with your keys. Wait for the time in Retry-After. |
| 429 | too_many_parallel | More than 2 requests at once with your keys. |
| 429 | upstream_busy | The model is busy or has reached its free limit for now. Try again later or choose another model. |
| 502 | upstream_error | The model provider did not answer. Try again shortly. |
| 503 | models_unavailable, model_unavailable | Models are temporarily unavailable. See the status page. |
Privacy
This site does not store your prompts or the answers. To produce an answer, your messages are sent to the model provider (Groq or OpenRouter). Read the privacy policy for details, including how the providers handle data.