POST /v1/chat/completions against OpenAI’s API will work against Piramyd with only a base_url change. The endpoint supports multi-turn conversations, tool/function calling, vision inputs, streaming via Server-Sent Events, and automatic context compaction for long threads.
Never hardcode a model ID. Always discover available models at runtime via
GET /v1/models and select one whose endpoints array includes /v1/chat/completions.Endpoint
Request Parameters
The ID of the model to use. Retrieve the live catalog from
GET /v1/models and use a model whose endpoints array includes /v1/chat/completions. Example: claude-opus-4.8.The conversation history as an array of message objects. Each message has a
role (system, user, assistant, or tool) and a content field. For multimodal messages, content may be an array of content parts (see Vision example below).Sampling temperature between
0 and 2. Lower values produce more focused, deterministic output; higher values produce more varied output. Use 0 for tasks that require consistent, reproducible responses.Maximum number of tokens to generate in the response. Set this explicitly — do not rely on the default when using tool calling with large arguments. Must not exceed the model’s
max_output_tokens from the catalog.Alias for
max_tokens, introduced in the newer OpenAI format. Use either; they are equivalent. If both are provided, max_completion_tokens takes precedence.Set to
true to receive the response as a stream of Server-Sent Events (SSE). Each chunk is a partial chat.completion.chunk object. The stream ends with data: [DONE].Additional options for streaming. Pass
{"include_usage": true} to receive a final usage chunk after the last content chunk and before [DONE]. Only meaningful when stream is true.An array of tool definitions the model may call. Each tool has a
type of "function" and a function object with name, description, and a JSON Schema parameters. Only send this field to models where supports_tools: true in the model catalog.Controls whether and how the model calls tools:
"auto"— the model decides (default when tools are present)"none"— the model will not call any tool"required"— the model must call at least one tool{"type": "function", "function": {"name": "..."}}— force a specific tool
An opaque string identifying the conversation thread. Providing this enables automatic context compaction: when the conversation approaches the model’s context limit, earlier messages are summarised transparently so the thread can continue indefinitely. See Context Compaction for details.
Number of completion choices to generate. Most upstream providers return exactly one completion regardless of this value; set to
1 for reliable behaviour.An integer seed for deterministic sampling. Support depends on the upstream model. Pass the same seed and request to get reproducible outputs.
An opaque string representing the end-user making the request. Used for abuse tracking and is passed through to upstream providers that support it.
Return log probabilities of output tokens. Accepted and passed through to upstream providers that support it; silently ignored by those that do not.
Number of top log-probability tokens to return per position. Requires
logprobs: true. Accepted and passed through where supported.Passed through to upstream providers that support conversation storage. Has no effect on Piramyd’s own context compaction logic — use
thread_id for that.Request Examples
Non-Streaming Response
Whenstream is false, the API returns a single chat.completion object.
The exact model ID that generated the response. May differ from what you requested if an alias was used.
Streaming Response
Whenstream: true, the API sends a series of SSE chunks, each prefixed with data: . The stream ends with data: [DONE].
Each chunk is a chat.completion.chunk object:
The incremental content for this chunk. On the first chunk,
delta.role is "assistant". Subsequent chunks carry delta.content with text fragments. The final content chunk has an empty delta and finish_reason set.Present only on the final usage-only chunk (after
finish_reason is set) when you pass stream_options: {"include_usage": true}. Contains prompt_tokens, completion_tokens, and total_tokens.When
finish_reason is "tool_calls" in a stream, accumulate all delta.tool_calls[i].function.arguments fragments before parsing the JSON. The API provides automatic tool call integrity protection — you will always receive complete, valid JSON by the time the stream ends.Legacy Endpoints
The legacy OpenAI completions endpoint. Accepts a
prompt string (not a messages array) and returns a single text continuation. Use /v1/chat/completions for all new integrations.