Chat Completions

The Chat Completions API is the primary endpoint for conversational AI. It supports text, vision (image input), function/tool calling, and streaming.

Endpoint

POST /v1/chat/completions

Request Body

Parameter	Type	Required	Description
model	string	✅	Model ID (e.g. gpt-4o, claude-sonnet-4-20250514, gemini-2.5-pro)
messages	array	✅	Conversation messages (see below)
temperature	number		Sampling temperature (0–2). Default: 1
top_p	number		Nucleus sampling. Default: 1
max_tokens	integer		Maximum tokens to generate
stream	boolean		Enable SSE streaming. Default: false
tools	array		Available tools/functions for the model to call
tool_choice	string/object		How the model should use tools
response_format	object		Force JSON output: {"type": "json_object"}
n	integer		Number of completions. Default: 1
stop	string/array		Stop sequences

Message Format

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain quantum computing briefly."},
    {"role": "assistant", "content": "Quantum computing uses..."},
    {"role": "user", "content": "Can you give an example?"}
  ]
}

Vision (Image Input)

Send images as part of a user message:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/image.jpg"}
        }
      ]
    }
  ]
}

Base64-encoded images are also supported:

{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}

Example Request

cURLPython

curl https://ai.moducompia.com/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_API_KEY",
    base_url="%%BASE_URL%%/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1723456789,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Streaming

Set "stream": true to receive partial results as Server-Sent Events:

curl https://ai.moducompia.com/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a joke"}],
    "stream": true
  }'

Each SSE event contains a delta:

{"id": "chatcmpl-abc", "choices": [{"delta": {"content": "Why"}, "index": 0}]}

The stream ends with data: [DONE].

Tool/Function Calling

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "What's the weather in Paris?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ]
}

When the model decides to call a tool, the response includes a tool_calls array instead of text content. Send the result back as a tool role message.