API console
POST/v1/chat/completions
Bash
curl https://spro.hridaai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spro-xxxxxxxxxxxxxxxx" \ -d '{ "model": "gpt-oss-20b", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "What is the capital of France?" } ], "temperature": 0.7 }'JSON
{ "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1756968000, "model": "gpt-oss-20b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The capital of France is Paris." }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 21, "completion_tokens": 8, "total_tokens": 29 }}POST https://spro.hridaai.com/v1/chat/completions
Creates a model response for the given chat conversation. Works with any provider in the catalog — just prefix the model ID with the provider, e.g. gpt-oss-20b.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
messages | array | Required | A list of messages comprising the conversation so far. Each message has a role (system, developer, user, assistant, or tool) and content. |
model | string | Required | Model ID to use, provider-prefixed — e.g. gpt-oss-20b, anthropic/claude-sonnet-4, google/gemini-2.5-flash. |
audio | object or null | Optional | Parameters for audio output. Required when audio output is requested with modalities: ["audio"]. |
frequency_penalty | number or null | Optional | Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far. Defaults to 0. |
logit_bias | map | Optional | Map of token IDs to an associated bias value from -100 to 100. |
logprobs | boolean or null | Optional | Whether to return log probabilities of the output tokens. Defaults to false. |
top_logprobs | integer or null | Optional | An integer between 0 and 20 specifying the number of most likely tokens to return at each position, when logprobs is set. |
max_completion_tokens | integer or null | Optional | An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. |
n | integer or null | Optional | How many chat completion choices to generate for each input message. Defaults to 1. |
parallel_tool_calls | boolean | Optional | Whether the model may make parallel tool calls. Defaults to true. |
presence_penalty | number or null | Optional | Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far. Defaults to 0. |
response_format | object | Optional | An object specifying the format the model must output. Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs. |
seed | integer or null | Optional | For deterministic sampling where supported — the same seed and parameters should return the same result. |
stop | string / array / null | Optional | Up to 4 sequences where the API will stop generating further tokens. |
stream | boolean or null | Optional | If set to true, the model response is sent as server-sent events as it is generated. Defaults to false. |
stream_options | object or null | Optional | Options for streaming response. Only used when stream: true — set {"include_usage": true} to get an extra chunk with usage stats. |
store | boolean or null | Optional | Whether to store the generated model response for later retrieval. |
temperature | number or null | Optional | Sampling temperature between 0 and 2. Higher values make output more random; lower values make it more focused and deterministic. Defaults to 1. |
tool_choice | string / object | Optional | Controls which tool the model calls. "none", "auto" (default), "required", or a specific function. |
tools | array | Optional | A list of tools the model may call — currently only functions are supported. |
top_p | number or null | Optional | Nucleus sampling: the model considers the results of tokens with top_p probability mass. Defaults to 1. |
user | string | Optional | A unique identifier representing your end user, to help monitoring and abuse detection. |
The message object
| Field | Type | Description |
|---|---|---|
role | string | The role of the message author — system, developer, user, assistant, or tool. |
content | string or array | The contents of the message. Can be a plain string or an array of content parts (text, image_url, audio). |
name | string | Optional name for the participant, used to differentiate between same-role participants. |
tool_calls | array | The tool calls generated by the model, when it decides to call a tool. |
tool_call_id | string | Tool call that this message is responding to — required on role: "tool" messages. |
The response object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the chat completion. |
object | string | Always chat.completion. |
created | integer | Unix timestamp of when the completion was created. |
model | string | The model used for the completion. |
choices | array | The list of generated completions — one per requested n. |
choices[].message | object | The generated message, with role and content. |
choices[].finish_reason | string | Why generation stopped — stop, length, tool_calls, or content_filter. |
usage | object | Token counts — prompt_tokens, completion_tokens, total_tokens. |
Streaming
With "stream": true, tokens are sent as server-sent events as they are generated:
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"The"}}]}
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" capital"}}]}
data: [DONE]Guardrails
If a guardrail detects a violation in the request and its action is set to block, Spro returns a 403 Forbidden and the request never reaches the model:
{ "error": { "message": "Request blocked by guardrail: sensitive_information_disclosure", "type": "guardrail_block", "code": "GUARDRAIL_BLOCKED" }}With other actions, the request proceeds — the violation is logged (log, warn) or the content is masked in place (redact) before the model sees it.
