HridaSpro Docs

Api Reference

Chat Completions

Create a model response for a chat conversation.

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

ParameterTypeRequiredDescription
messagesarrayRequiredA list of messages comprising the conversation so far. Each message has a role (system, developer, user, assistant, or tool) and content.
modelstringRequiredModel ID to use, provider-prefixed — e.g. gpt-oss-20b, anthropic/claude-sonnet-4, google/gemini-2.5-flash.
audioobject or nullOptionalParameters for audio output. Required when audio output is requested with modalities: ["audio"].
frequency_penaltynumber or nullOptionalNumber 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_biasmapOptionalMap of token IDs to an associated bias value from -100 to 100.
logprobsboolean or nullOptionalWhether to return log probabilities of the output tokens. Defaults to false.
top_logprobsinteger or nullOptionalAn integer between 0 and 20 specifying the number of most likely tokens to return at each position, when logprobs is set.
max_completion_tokensinteger or nullOptionalAn upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
ninteger or nullOptionalHow many chat completion choices to generate for each input message. Defaults to 1.
parallel_tool_callsbooleanOptionalWhether the model may make parallel tool calls. Defaults to true.
presence_penaltynumber or nullOptionalNumber 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_formatobjectOptionalAn object specifying the format the model must output. Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs.
seedinteger or nullOptionalFor deterministic sampling where supported — the same seed and parameters should return the same result.
stopstring / array / nullOptionalUp to 4 sequences where the API will stop generating further tokens.
streamboolean or nullOptionalIf set to true, the model response is sent as server-sent events as it is generated. Defaults to false.
stream_optionsobject or nullOptionalOptions for streaming response. Only used when stream: true — set {"include_usage": true} to get an extra chunk with usage stats.
storeboolean or nullOptionalWhether to store the generated model response for later retrieval.
temperaturenumber or nullOptionalSampling temperature between 0 and 2. Higher values make output more random; lower values make it more focused and deterministic. Defaults to 1.
tool_choicestring / objectOptionalControls which tool the model calls. "none", "auto" (default), "required", or a specific function.
toolsarrayOptionalA list of tools the model may call — currently only functions are supported.
top_pnumber or nullOptionalNucleus sampling: the model considers the results of tokens with top_p probability mass. Defaults to 1.
userstringOptionalA unique identifier representing your end user, to help monitoring and abuse detection.

The message object

FieldTypeDescription
rolestringThe role of the message author — system, developer, user, assistant, or tool.
contentstring or arrayThe contents of the message. Can be a plain string or an array of content parts (text, image_url, audio).
namestringOptional name for the participant, used to differentiate between same-role participants.
tool_callsarrayThe tool calls generated by the model, when it decides to call a tool.
tool_call_idstringTool call that this message is responding to — required on role: "tool" messages.

The response object

FieldTypeDescription
idstringUnique identifier for the chat completion.
objectstringAlways chat.completion.
createdintegerUnix timestamp of when the completion was created.
modelstringThe model used for the completion.
choicesarrayThe list of generated completions — one per requested n.
choices[].messageobjectThe generated message, with role and content.
choices[].finish_reasonstringWhy generation stopped — stop, length, tool_calls, or content_filter.
usageobjectToken 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.