Create chat completion

curl -X POST 'https://ws.orchestrivo.com/api/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Capital of Canada?"}]
  }'

{
  "id": "chatcmpl-9a3f8c2b14d6e7",
  "object": "chat.completion",
  "created": 1747315920,
  "model": "claude-sonnet-4-5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Ottawa."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 1,
    "total_tokens": 13
  }
}

POST

chat

completions

curl -X POST 'https://ws.orchestrivo.com/api/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Capital of Canada?"}]
  }'

{
  "id": "chatcmpl-9a3f8c2b14d6e7",
  "object": "chat.completion",
  "created": 1747315920,
  "model": "claude-sonnet-4-5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Ottawa."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 1,
    "total_tokens": 13
  }
}

Which models and fields are supported?

OpenRouter’s reasoning, plugins, provider, modalities and image_config fields are accepted too.Image-generation models (gpt-image-*, gemini-*-image-preview) run when modalities includes "image" and return image attachments on choices[0].message.images. Decision models (typesafe/jev-*) are not chat models. Send those to POST /decisions.

Which host serves this endpoint, and how does streaming work?

Chat completions are served from the streaming host, POST https://ws.orchestrivo.com/api/v1/chat/completions, for both stream: true and stream: false. api.orchestrivo.com does not serve this endpoint. The Python SDK routes there automatically.With stream: true the response is text/event-stream (Server-Sent Events). Each event carries one chat.completion.chunk and the stream ends with data: [DONE]. client.chat.completions.create(..., stream=True) yields parsed ChatStreamChunk objects.

How do I send tool calls and images?

Send messages in the OpenAI shape and Orchestrivo translates them for the model’s provider (Anthropic, OpenAI, and Google Gemini). Models served through OpenRouter and other OpenAI-compatible providers receive the messages as sent.

Tool-result turns: after the model replies with finish_reason: "tool_calls", append its assistant message (with tool_calls) and one {"role": "tool", "tool_call_id": ..., "content": ...} message per call, then send the conversation again. Every tool call needs a matching tool message, and every tool message must match a tool call in an earlier assistant message.
Images: user messages accept image_url content parts alongside text parts. The URL can be an http(s) URL or a base64 data URL (data:image/png;base64,...). Images must be JPEG, PNG, GIF, or WebP and at most 20 MB. Redirects are not followed when downloading an image.
tool_choice: "auto" (the default when tools are sent), "none", "required", or {"type": "function", "function": {"name": "..."}} to force one tool.
developer messages are treated like system messages.

{
  "model": "claude-sonnet-4-5",
  "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}],
  "messages": [
    {"role": "user", "content": [
      {"type": "text", "text": "What's the weather where this photo was taken?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]},
    {"role": "assistant", "content": null, "tool_calls": [
      {"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Ottawa\"}"}}
    ]},
    {"role": "tool", "tool_call_id": "call_1", "content": "12°C and sunny"}
  ]
}

A request that can’t be translated returns 400 invalid_request with param set to the field at fault (for example messages[3].tool_call_id). When the provider itself rejects the request (HTTP 400, 404, 413, or 422), the error message relays the provider’s reason, prefixed with The provider rejected the request:.

How are chat completions billed?

Each completion charges the caller’s credit balance based on the model’s token usage (with cache-token semantics per provider). Image-generation calls are priced the same way, from the usage the image model reports. On usage-based pricing, a call that runs on your own provider API key (BYOK) uses 0 model credits. Organizations still on legacy pricing get a partial BYOK discount instead. See Credits.Orchestrivo checks credits before sending the request to a provider. Insufficient credits return HTTP 402 credit_limit_exceeded. A provider call whose cost is fully waived because you use your own API key is exempt from this preflight.

Authorizations

Authorization

string

header

required

A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.

Body

application/json

model

string

required

Model slug. Use the id from GET /models or one of Orchestrivo's preset routes.

Example:

"claude-sonnet-4-5"

messages

object[]

required

Conversation history. Roles system, developer, user, assistant, and tool. User messages accept multipart content with text and image_url parts. Assistant messages can carry tool_calls; answer each one with a tool message whose tool_call_id matches the call's id.

Example:

[
  {
    "role": "user",
    "content": "Capital of Canada?"
  }
]

stream

boolean

default:false

When true, the response is text/event-stream carrying one chat.completion.chunk per delta and terminating with data: [DONE]. Otherwise a unary JSON chat.completion is returned.

temperature

number

Sampling temperature.

max_completion_tokens

integer

Cap on completion tokens. Replaces the deprecated max_tokens field.

modalities

enum<string>[]

Output modalities. Include "image" to route to an image-generation model.

Available options:

text,

image

image_config

object

Image-generation parameters (size, quality, aspect_ratio, background, output_format, partial_images). Optional. Image-generation models accept either modalities: ["image"] or image_config (or both); chat models ignore this field.

response_format

object

Constrain the response. {type: "json_object"} returns a JSON object; {type: "json_schema", json_schema: {name, strict, schema}} returns JSON matching the supplied schema.

tools

array

OpenAI-shape tool definitions ({type: "function", function: {name, description, parameters}}). Pass tool_choice to constrain selection.

tool_choice

"auto" lets the model choose and is the default when tools are sent. "none" disables tool calls, "required" forces a tool call, and {"type": "function", "function": {"name": "..."}} forces a specific tool.

Example:

"auto"

provider

object

OpenRouter provider routing config. Caller fields like sort and order are honored; ZDR/data_collection policy is server-enforced.

reasoning

object

Reasoning settings. effort accepts minimal, low, medium, high, xhigh, max, or none. On Claude models, an unknown effort returns HTTP 400 with param set to reasoning.effort. Claude models return their thinking summary in the response's reasoning; none turns thinking off on Claude models that support disabling it. Only effort and summary are read from this object; other fields are ignored.

Response

Chat completion. When stream is false (or omitted), the response is the chat.completion envelope below. When stream: true, the response is text/event-stream; each event carries one chat.completion.chunk and the terminator is data: [DONE].

string

Example:

"chatcmpl-9a3f8c2b14d6e7"

object

string

Example:

"chat.completion"

created

integer

Example:

1747315920

model

string

Example:

"claude-sonnet-4-5"

choices

object[]

Show child attributes

usage

object

Show child attributes

Core concepts

Agents

Sessions

Skills

Artifacts

MCP

Browser profiles

Personal wiki

Evaluations

Organization evaluations

Brain

Teams

Models

File operations

Enterprise organization

Create chat completion

Authorizations

Body

Response