API Reference

OpenAI-compatible API

OdinClaw implements the OpenAI REST API format. Change your base_url and API key — nothing else. This page documents the supported endpoints, supported request fields on /chat/completions, and honest limitations.

Base URL and authentication

Base URL

https://api.claw.odin-labs.ai/v1

Auth header

Authorization: Bearer YOUR_API_KEY

curl

curl https://api.claw.odin-labs.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ODINCLAW_API_KEY" \
  -d '{
    "model": "deepseek-v3",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ODINCLAW_API_KEY"],
    base_url="https://api.claw.odin-labs.ai/v1",
)

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

Node / TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ODINCLAW_API_KEY,
  baseURL: 'https://api.claw.odin-labs.ai/v1',
});

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

Supported endpoints

Method	Endpoint	Description	Status
POST	`/v1/chat/completions`	Chat completions — streaming and non-streaming. Core endpoint.	Supported
GET	`/v1/models`	List available models. Returns OdinClaw model IDs.	Supported
POST	`/v1/embeddings`	Text embeddings. Model: text-embedding-3-small compatible.	Supported
POST	`/v1/completions`	Legacy text completions (non-chat). Limited model support.	Partial
POST	`/v1/images/generations`	Image generation. Not yet available.	Not supported
POST	`/v1/audio/transcriptions`	Audio transcription (Whisper). Not yet available.	Not supported
POST	`/v1/audio/speech`	Text-to-speech. Not yet available.	Not supported
POST	`/v1/fine_tuning/jobs`	Fine-tuning. Not planned.	Not supported

/chat/completions — supported fields

All fields in the OpenAI chat completions request body. OdinClaw passes supported fields through to the underlying model provider; unsupported fields are silently dropped (never error on unknown fields).

Field	Type	Status	Notes
`model`	`string`	Yes	Required. Use OdinClaw model IDs (e.g. "deepseek-v3", "gemini-2.5-flash").
`messages`	`array`	Yes	Required. Roles: system, user, assistant, tool.
`temperature`	`number`	Yes	0.0–2.0. Passed through to provider.
`max_tokens`	`integer`	Yes	Upper bound on output tokens.
`stream`	`boolean`	Yes	Server-sent events (SSE). Same chunk format as OpenAI.
`top_p`	`number`	Yes	Nucleus sampling. Passed through to provider.
`stop`	`string \| array`	Yes	Stop sequences. Passed through where provider supports.
`n`	`integer`	Yes	Number of completions. Default 1. Provider-dependent for n>1.
`tools`	`array`	Yes	Tool-use / function calling. Supported on DeepSeek V3, Gemini Flash, Claude models.
`tool_choice`	`string \| object`	Yes	"auto", "none", or specific tool. Model-dependent behaviour.
`response_format`	`object`	Yes	{"type":"json_object"} supported on most models. Varies by provider.
`seed`	`integer`	No	Not forwarded — OdinClaw's routing layer does not guarantee determinism.
`logprobs`	`boolean`	No	Not supported. Provider APIs do not expose logprobs uniformly.
`top_logprobs`	`integer`	No	Not supported.
`user`	`string`	No	Accepted but not forwarded. Use your own user tracking.
`presence_penalty`	`number`	No	Passed through on OpenAI-native model routing only; ignored on other providers.
`frequency_penalty`	`number`	No	Same as presence_penalty — provider-dependent.

Streaming

Set stream: true (or stream=True in Python) to receive server-sent events (SSE). The chunk format is identical to OpenAI's streaming response — each chunk contains choices[].delta.content and is terminated by [DONE].

streaming.py

stream = client.chat.completions.create(
    model="deepseek-v3",
    messages=[{"role": "user", "content": "Write a haiku about the EU."}],
    stream=True,
)

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

Tool use / function calling

Tool-use follows the OpenAI tool-calling schema. Pass tools as an array of function definitions. Supported on DeepSeek V3, Gemini 2.5 Flash, and Claude models. Not yet available on all models — check the model page for per-model capability flags.

tool-use.py

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v3",
    messages=[{"role": "user", "content": "What's the weather in Berlin?"}],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name)       # get_current_weather
print(tool_call.function.arguments)  # {"city": "Berlin"}

What is NOT supported

Honest limitations. We prefer to document gaps over hiding them.

Image generation (/v1/images/generations)

Not available. No current timeline.

Audio transcription and text-to-speech

Not available on the current API. Use a dedicated Whisper endpoint or dedicated TTS provider.

Fine-tuning (/v1/fine_tuning/jobs)

Not planned. OdinClaw is a routing gateway, not a training platform.

Assistants API (threads, runs, files)

Not supported. The Assistants API is stateful; OdinClaw is a stateless gateway.

logprobs / top_logprobs

Not supported across providers. Silently dropped.

seed (deterministic sampling)

Accepted but not forwarded. OdinClaw's routing layer does not guarantee per-provider determinism.

Batch API (/v1/batches)

Not supported. Coming in a future release.

Moderation (/v1/moderations)

Not supported.

Known issues

Tool-use streaming varies by model

Tool-call events in streaming mode follow the OpenAI chunk format, but the granularity of argument streaming differs across providers. DeepSeek V3 and Claude stream tool-arguments token-by-token; Gemini Flash may emit the full argument JSON in a single chunk. Parse with index-based chunk accumulation, not line-based.

"model" field in response may differ from request

The response.model field reflects the provider's internal model identifier, which may not exactly match the OdinClaw model ID you sent. Do not use response.model for billing attribution — use the OdinClaw request ID from the x-request-id response header.

Rate limits are per-tier, not per-model

OdinClaw rate limits are applied at the gateway tier level, not per-model. If you're on the free tier and hit the limit, switching model IDs in the same request will not help — the request will still be rate-limited.

context_length_exceeded error shape

OdinClaw returns a 400 with error.code "context_length_exceeded" and error.type "invalid_request_error" when your prompt exceeds the model's context window. The exact message is provider-forwarded and may not be identical to OpenAI's wording — do not pattern-match on the exact message string.

Available models

Use GET /v1/models to fetch the current list programmatically. The full model registry with per-model pricing, context window, and capability flags is at /models.

DeepSeek V3

deepseek-v3

$0.26/$1.10 per 1M · 64K ctx

Gemini 2.5 Flash

gemini-2.5-flash

$0.30/$2.50 per 1M · 1M ctx

Claude 3.5 Haiku

claude-3-5-haiku

Fast, compact reasoning

Llama 3.3 70B

llama-3.3-70b

Open-weights, balanced

Full list at /models. Model IDs and availability change — use GET /v1/models for the live list.

Ready to start?

Free tier — 100K tokens per month, no credit card, hard spend cap at €0. Get your API key in under 60 seconds.

Get free API key Back to docs