Quickstart

Tokentide speaks the OpenAI API and the Venice API. If your code already works with OpenAI or Venice, switching takes two changes:

1. Base URL: https://api.tokentide.app/v1
2. API key: a Tokentide key, tt_live_…

Everything else (request bodies, streaming, tools, structured output, venice_parameters) stays the same.

1. Create an API key#

Create a key in the dashboard under API keys (tokentide.app/app/keys). It is shown once; afterwards you only see tt_live_… plus its last four characters. Store it in an environment variable:

export TOKENTIDE_API_KEY="tt_live_…"

Key settings you can change later:

Keys come in two kinds: tt_live_… works only in production; tt_test_… works only on preview and staging deployments, which answer from a deterministic mock instead of real models. Venice API keys are never accepted.

2. Make your first request#

Pick your client. Every example sends the same chat completion; only the base URL and the key differ from what you would write for OpenAI.

curl https://api.tokentide.app/v1/chat/completions \
  -H "Authorization: Bearer $TOKENTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -D - \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{ "role": "user", "content": "Explain the tides in one sentence." }]
  }'

The body is the standard OpenAI chat.completion object. LlamaIndex and other OpenAI-compatible clients work the same way: set the base URL and the key.

3. See what you paid#

Every priced response tells you what it cost in its headers (values are illustrative):

x-request-id: req_01JDV6Q7Z8R2M3N4P5Q6R7S8T9
x-tokentide-lane: standard
x-tokentide-multiplier: 0.655078
x-tokentide-epoch: 2026-10-31
x-tokentide-cross-epoch: false
x-tokentide-list-cost-usd: 0.000042
x-tokentide-charge-usd: 0.000028
x-tokentide-model-privacy: private
x-ratelimit-limit-requests: 600
x-ratelimit-remaining-requests: 599
x-ratelimit-reset-requests: 60s

• X-Tokentide-Multiplier is the fraction of the Venice list price you pay (here about 34% below list). It is locked when the request is admitted.
• X-Tokentide-Charge-USD is what was deducted from your balance; X-Tokentide-List-Cost-USD is what Venice would have charged at its list price.
• Quote X-Request-Id when you contact support. It maps to the request’s metadata record, never its content.

Read the headers, and send Tokentide request headers, from your SDK:

raw = client.chat.completions.with_raw_response.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Explain the tides in one sentence."}],
    extra_headers={"X-Tokentide-Max-Multiplier": "0.70"},
)
completion = raw.parse()
print(raw.headers.get("x-tokentide-multiplier"), raw.headers.get("x-tokentide-charge-usd"))
print(raw.headers.get("x-request-id"))

Every response header is described in Lanes and Tide Pricing.

4. Stream responses#

Streaming works unchanged (server-sent events, data: [DONE] at the end). The price headers known at admission (X-Tokentide-Multiplier, -Lane, -Epoch, -Cross-Epoch) arrive with the response headers. The final cost is only known when the stream ends, so it arrives in the final usage chunk instead of a header:

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":31,"total_tokens":45},"cost":{"usd":0.000028,"diem":0},"tokentide":{"list_cost_usd":"0.000042","multiplier":"0.655078","lane":"standard","epoch":"2026-10-31","savings_usd":"0.000014"}}
 
data: [DONE]

• cost is rewritten to your charge in USD (diem is always 0), so Venice-aware clients show what you paid.
• tokentide adds the Venice list cost, the locked multiplier, the lane, the epoch and your saving.
• While a model is thinking silently, Tokentide sends SSE comment lines (: keep-alive) every 15 seconds. SSE clients ignore them.

stream = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    elif chunk.usage:
        extra = chunk.model_extra or {}
        print("\ncharged:", extra.get("cost"), extra.get("tokentide"))

5. Venice parameters#

Venice-only fields go in the request body exactly as with Venice. With the OpenAI SDKs, pass them through extra_body:

client.chat.completions.create(
    model="zai-org-glm-5-2",
    messages=[{"role": "user", "content": "Summarize this paragraph: …"}],
    extra_body={"venice_parameters": {"include_venice_system_prompt": False}},
)

6. Venice SDKs and raw Venice clients#

Every host also serves the Venice path layout under /api/v1/*. Point a Venice client at https://api.tokentide.app/api/v1 and use your Tokentide key:

curl https://api.tokentide.app/api/v1/models -H "Authorization: Bearer $TOKENTIDE_API_KEY"

7. Pick a model#

GET /v1/models returns the Venice catalog filtered to what your key may call, with Venice’s list prices plus a tokentide object holding your current prices in both lanes:

{
  "id": "deepseek-v4-1-flash",
  "type": "text",
  "model_spec": { "privacy": "private", "pricing": { "input": { "usd": 0.3 }, "output": { "usd": 1.2 } } },
  "tokentide": {
    "privacy_tier": "private",
    "standard": {
      "multiplier": "0.655078",
      "input_per_1m": "0.196524",
      "output_per_1m": "0.786094",
      "per_unit": null,
      "unit": null
    },
    "lowtide": {
      "open": true,
      "eligible": true,
      "multiplier": "0.458555",
      "input_per_1m": "0.137567",
      "output_per_1m": "0.550266",
      "per_unit": null,
      "unit": null
    },
    "price_locked_until": null,
    "epoch": "2026-10-31"
  }
}

New keys default to privacy mode private, so only Private, TEE and E2EE models are listed. Anonymized models (for example Claude, GPT and Gemini models) need a key with privacy mode all; otherwise they answer 403 model_not_allowed. The pricing page shows every model with its live price.

Next steps#

• Pay less for batch work with the Low Tide lane or the client-side Tide Runner.
• Handle errors and retries: Errors and Rate limits.
• Add credit, turn on auto top-up and set spending limits and alerts: Billing and spending limits.
• Try any endpoint from the browser with the API console in the API reference.