Chat Completions

POST /v1/chat/completions

Generate a response from a model given a conversation history. This is the most commonly used endpoint and supports all OpenAI-compatible models.

Request Body

Parameter	Type	Required	Description
`model`	string	Yes	Model ID to use, e.g. `gpt-5.4-mini`, `claude-sonnet-4-6`
`messages`	array	Yes	Array of message objects representing the conversation
`stream`	boolean	No	If `true`, stream tokens as SSE. Default: `false`
`temperature`	number	No	Sampling temperature 0–2. Default: `1`
`max_tokens`	integer	No	Maximum tokens to generate
`top_p`	number	No	Nucleus sampling probability. Default: `1`
`n`	integer	No	Number of completions to generate. Default: `1`
`stop`	string or array	No	Stop sequences
`presence_penalty`	number	No	Penalty for new token presence (-2 to 2)
`frequency_penalty`	number	No	Penalty for token frequency (-2 to 2)
`user`	string	No	End-user identifier for abuse detection
`tools`	array	No	List of tools (functions) the model can call
`tool_choice`	string or object	No	Controls tool selection

Message Object

{
  "role": "user" | "assistant" | "system" | "tool",
  "content": "string or array of content parts",
  "name": "optional name",
  "tool_calls": [...],
  "tool_call_id": "..."
}

Example Request

curl https://api.soxai.io/v1/chat/completions \
  -H "Authorization: Bearer $SOXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are a senior software engineer specializing in distributed systems."
      },
      {
        "role": "user",
        "content": "Explain the CAP theorem in simple terms."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Example Response

{
  "id": "chatcmpl-01jq4abc",
  "object": "chat.completion",
  "created": 1743350400,
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The CAP theorem states that a distributed system can guarantee at most two of three properties: Consistency, Availability, and Partition Tolerance..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 187,
    "total_tokens": 229
  }
}

Tool Calling (Function Calling)

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "user", "content": "What is the weather in Tokyo?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

SoxAI-Specific Headers

Header	Description
`X-Session-ID`	Bind requests to a specific upstream provider (session stickiness)

Finish Reasons

Value	Meaning
`stop`	Model reached a natural stopping point
`length`	Hit `max_tokens` limit
`tool_calls`	Model wants to call a function
`content_filter`	Blocked by provider content policy

Chat Completions

On this page