Chat Completions

POST /v1/chat/completions is the OpenAI-compatible text endpoint, and the one most SDKs, frameworks and tools speak. Every text model in the catalogue answers on it — including Claude, Gemini and open-weight models — so one request shape covers all of them.

A request

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.cloakray.com/v1",
  apiKey: process.env.CLOAKRAY_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Name three uses for a quartz crystal." },
  ],
  max_tokens: 300,
});

console.log(completion.choices[0].message.content);

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.cloakray.com/v1", api_key=os.environ["CLOAKRAY_API_KEY"])

completion = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Name three uses for a quartz crystal."},
    ],
    max_tokens=300,
)
print(completion.choices[0].message.content)

Messages

messages is the whole conversation, oldest first. The endpoint keeps no state between calls, so send the history you want the model to see every time.

Role	Use it for
`system` or `developer`	Instructions that frame the conversation.
`user`	What the person said. `content` is a string, or an array of parts for images and documents.
`assistant`	The model's earlier replies, including any `tool_calls` it made.
`tool`	The result of a tool call, with the matching `tool_call_id`.

Parameters

Parameter	What it does
`model`	Required. A model ID from the catalogue.
`messages`	Required. The conversation.
`max_tokens` / `max_completion_tokens`	Cap on the reply length. Keep it within the model's `max_output_tokens`.
`temperature`, `top_p`	Sampling. Lower is more deterministic. Some reasoning models ignore or reject them.
`stop`	One or more strings that end generation.
`stream`	`true` to receive tokens as they are generated — see streaming.
`tools`, `tool_choice`	Functions the model may call — see tool calling.
`response_format`	JSON mode or a JSON schema — see structured outputs.
`reasoning_effort`	How hard a reasoning model thinks — see reasoning.

Parameters are passed to the model as you send them. A model that does not support one may ignore it or return a 400 that says so; the model's page lists what it supports.

The response

{
  "id": "chatcmpl-8f2c...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. Oscillators in watches..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 64,
    "total_tokens": 95,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "cost": 0.001053,
    "cost_details": { "input_cost": 0.000093, "output_cost": 0.00096, "total_cost": 0.001053 }
  }
}

finish_reason is stop when the model finished, length when it hit max_tokens, tool_calls when it wants a tool result, and content_filter when the model declined. model is always the ID you asked for.

usage is what the request is billed on: input tokens, output tokens, and where they apply, cached and reasoning tokens. usage.cost is the amount charged for this request in US dollars, with your discount already applied, and cost_details breaks it down. See usage and cost for every endpoint's fields.

Other SDKs and languages

Anything that speaks the OpenAI format works with the base URL https://api.cloakray.com/v1: the official OpenAI SDKs in every language, the Vercel AI SDK, LangChain, LlamaIndex, and plain HTTP.