Quickstart

TokenOcean speaks the OpenAI API. If your code already calls OpenAI, you change two things: the base_url and the API key. Nothing else.

Base URL

Use this for every endpoint. The OpenAI SDKs want the /v1 suffix, so pass __ORIGIN__/v1 as base_url.

Authentication

Send your key as a bearer token — this is what every OpenAI SDK does for you:

Authorization: Bearer YOUR_API_KEY

The legacy X-API-Key: YOUR_API_KEY header also works if you cannot set Authorization. Keys are 64 characters and are case-sensitive. Never ship a key in client-side code — call the API from your server.

Your first request

First find out which models this deployment serves (names differ between upstream providers):

curl __ORIGIN__/v1/models \
  -H "Authorization: Bearer $TOKENOCEAN_API_KEY"

Pick any id from the response and use it as model below.

cURL

export TOKENOCEAN_API_KEY="YOUR_API_KEY"

curl __ORIGIN__/v1/chat/completions \
  -H "Authorization: Bearer $TOKENOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [
      {"role": "user", "content": "Explain vector databases in one paragraph."}
    ]
  }'

Python (openai SDK)

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="__ORIGIN__/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

Node.js / TypeScript (openai SDK)

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "__ORIGIN__/v1",
  apiKey: process.env.TOKENOCEAN_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);

Streaming

Set stream: true and read server-sent events. Works the same as OpenAI:

stream = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Count to ten."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Usage is metered as the stream ends. The final response header X-Token-Balance-Remaining tells you the balance left afterwards.

Billing

Credits are prepaid and never expire. One credit equals one input token, and output tokens are charged at a higher rate because upstream providers charge more for them:

credits_charged = prompt_tokens × input_rate + completion_tokens × output_rate

• The rate per model is shown on your dashboard after your first call.
• Before each request we reserve max_tokens × output_rate. If your balance cannot cover it, the request is rejected with 402 and nothing is sent upstream — you are never billed for a request that could not finish.
• Set a smaller max_tokens if you get 402 on a large balance-light account.
• Reasoning models. deepseek-flash and deepseek-v4-pro think before they answer: the thinking arrives in the non-standard reasoning_content field while the answer itself is in content. Reasoning tokens are billed as output tokens. If max_tokens is too small the model can spend the whole budget thinking and return finish_reason: "length" with an empty content — and that call is still billed. Use max_tokens ≥ 500 with these models.

Errors

Errors come back as {"error": {"message": ..., "type": ...}} with an HTTP status that matches.

A successful call also returns X-Token-Balance-Remaining so you can meter your own spend without polling the dashboard.

Using other tools

Any client with an "OpenAI compatible" or "custom base URL" setting works — LangChain, LlamaIndex, Dify, n8n, LibreChat, Cline, and similar. Fill in:

• Base URL: __ORIGIN__/v1
• API key: your TokenOcean key
• Model: an id from /v1/models

Some editors and plugins assume OpenAI's sk- key prefix and refuse keys that do not start with it. TokenOcean keys are 64-character opaque strings, so if a client rejects yours for that reason, use a client that does not enforce the prefix.

FAQ