API reference
Every endpoint the LuluTokens relay exposes, the headers it accepts, and the errors it returns.
LuluTokens is a relay. It speaks three wire formats — OpenAI, OpenAI Responses, and Anthropic Messages — and forwards to whichever provider serves the model you named. There is no LuluTokens-specific request format to learn: if your client already talks to one of those three, it already talks to us.
Base URL
https://api.lulutokens.ai/v1
Auth
Authorization: Bearer sk-...
Authentication
Every request needs a key from the console. The standard header works everywhere:
Authorization: Bearer sk-...Two provider-specific alternatives are accepted so that unmodified SDKs work:
| Header | Accepted on | Used by |
|---|---|---|
x-api-key | /v1/messages, /v1/models | Anthropic SDK, Claude Code |
x-goog-api-key | /v1beta/*, /v1/models/* | Google GenAI SDK |
The Gemini convention of passing the key in the query string — ?key=sk-... —
is also accepted, but do not use it. Query strings are recorded in access
logs and proxy logs in full, where headers are not, so a key sent that way ends
up written to disk in plaintext. Send x-goog-api-key instead.
Endpoints
Only the paths below are routed. Anything else returns 404 at the edge, before
it reaches the gateway — account, billing and admin operations live in the
console, not on api..
OpenAI format
| Method | Path | Use it for |
|---|---|---|
GET | /v1/models | List the models your key can reach |
GET | /v1/models/{model} | Retrieve one model |
POST | /v1/chat/completions | The default for almost every client |
POST | /v1/embeddings | Embeddings — see the note below |
POST | /v1/images/generations | Text to image |
POST | /v1/images/edits | Image editing |
POST | /v1/edits | Image editing, legacy path |
OpenAI Responses format
| Method | Path | Use it for |
|---|---|---|
POST | /v1/responses | Codex CLI and other Responses-API clients |
POST | /v1/responses/compact | Codex context compaction |
POST | /v1/alpha/search | Codex standalone web search |
Anthropic format
| Method | Path | Use it for |
|---|---|---|
POST | /v1/messages | Claude Code and Anthropic SDK clients |
The Anthropic base URL is https://api.lulutokens.ai without /v1 — the
Anthropic client appends /v1/messages itself. Every other format wants the
/v1 included. This one difference causes more setup failures than anything
else on this page.
Gemini format
| Method | Path | Use it for |
|---|---|---|
GET | /v1beta/models | List, Gemini-shaped |
GET | /v1beta/openai/models | List, OpenAI-shaped |
POST | /v1beta/models/{model}:{action} | Native Gemini relay, e.g. :generateContent |
Video
For the doubao-seedance models. Both shapes reach the same backend — submit,
then poll for the result.
| Method | Path | Use it for |
|---|---|---|
POST | /v1/video/generations | Submit a job |
GET | /v1/video/generations/{id} | Poll it |
POST | /v1/videos | Submit, OpenAI-compatible shape |
GET | /v1/videos/{id} | Poll it |
GET | /v1/videos/{id}/content | Download the finished video |
POST | /v1/videos/{id}/remix | Edit an existing result |
/v1/embeddings is routed, but no model in the current catalogue is an
embedding model. A call reaches the gateway and is rejected because the model has
no price — an unpriced model is refused, never billed as free. Check
Models before building against it.
Not exposed
Deliberately 404, because nothing we sell uses them: /v1/audio/*,
/v1/rerank, /v1/files, /v1/fine-tunes, /v1/moderations, /v1/realtime,
the legacy /v1/completions, and the Midjourney, Suno, Kling and Jimeng task
routes.
If you need one of these, ask — opening a path is a configuration change on our side, not a code change on yours.
Errors
Errors come back as JSON with an error object:
{
"error": {
"code": "",
"message": "Invalid token (request id: 202608130951046830461698268d9d68VnCnMQr)",
"type": "new_api_error"
}
}The request id is inside the message, not in a separate field. Quote it when you contact support — it is how a request is found in the logs.
| Status | Meaning | What to do |
|---|---|---|
400 | Bad request, or a model your key cannot reach | Verify the model ID against /v1/models |
401 | Missing or invalid key | Check the Authorization: Bearer header |
402 | Out of credit | Top up in the console. There is no grace period and no negative balance |
404 | Path not routed | See below — the content type tells you which layer answered |
429 | Rate limited | Back off and retry |
5xx | Upstream provider error | Retry, or fall back to another model |
Telling the two 404s apart. A 404 with Content-Type: application/json came
from the gateway: the path is routed, but the thing you asked for does not exist.
A 404 with Content-Type: text/plain and the body Not found came from the
edge: that path is not exposed at all, and the request never reached the gateway
or your usage log. The second kind is almost always a base URL missing /v1, or
a client calling an endpoint from the "not exposed" list above.
Usage and cost
Every response carries a usage object with the token counts the request was
billed on. Cached input tokens, where a model supports caching, are reported
separately and billed at the lower cache rate.
Our metering records are what you are charged on — not a client-side tokenizer estimate. The console's request log shows the exact cost, model, token counts and timestamp of every individual request, and the ratios that were applied to it.