Core API

Chat completions

The workhorse endpoint. Identical to OpenAI's /v1/chat/completions in request and response shape, with a few additional tags + headers we add for observability and attribution.

Endpoint

POSThttps://api.ollima.com/v1/chat/completions

Request parameters

Field	Type	Req?	Description
`model`	string	YES	Alias (`deepseek-v4`) or long form (`tensorzero::model_name::<v>::<m>`).
`messages`	array	YES	Conversation. See Message roles.
`temperature`	0–2	no	Default `0.7`. 0 ≈ deterministic.
`top_p`	0–1	no	Nucleus sampling. Default `1`.
`max_tokens`	integer	no	Cap on completion length. Default varies by model.
`stream`	boolean	no	`true` → SSE. See Streaming.
`stream_options`	object	no	`{include_usage: true}` emits a terminal `usage` chunk.
`tools`	array	no	Function definitions. See Tool calling.
`tool_choice`	string/object	no	`"auto"` \| `"none"` \| `"required"` \| `{type,function}`.
`response_format`	object	no	`{"type":"json_object"}`. See Structured outputs.
`frequency_penalty`	-2 to 2	no	Penalize repeats.
`presence_penalty`	-2 to 2	no	Encourage novel topics.
`stop`	string/array	no	Stop sequences.
`user`	string	no	End-user identifier; captured as a tag.
`seed`	integer	no	Best-effort reproducibility (provider-dependent).

Response shape

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1781449284,
  "model": "deepseek-v4",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 47, "total_tokens": 59 }
}

Ollima-added response headers:

Header	Meaning
`X-Ollima-Request-Id`	UUIDv7 — share with support, search your activity log.
`X-RateLimit-Remaining-Plan`	Requests left in the current minute on your plan.
`X-RateLimit-Reset-Plan`	Unix seconds when the per-minute counter resets.

Message roles

Role	Used for
`system`	Persistent instructions. First message by convention.
`user`	Human input.
`assistant`	Prior model responses; may carry `tool_calls`.
`tool`	Result of a tool call. Must include `tool_call_id`.

Image inputs

For vision-capable models, pass an array of content blocks instead of a string:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What's in this image?"},
    {"type": "image_url", "image_url": {"url": "https://…/cat.jpg"}}
  ]
}

Or use a data: URL for inline base64. Models that don't support vision return 400.