Chat Completions

POST /v1/chat/completions creates a model response for a conversation. The shape is OpenAI-compatible; any OpenAI SDK client works unchanged.

Request

Body

Field	Type	Required	Description
`model`	`string`	Yes	Model slug from the catalog.
`messages`	`Message[]`	Yes	Conversation history. See `Message` below.
`stream`	`boolean`	No	Stream tokens via SSE. Default `false`.
`temperature`	`number`	No	0–2. Default `1`.
`max_tokens`	`integer`	No	Cap on output tokens. Default is model-specific.
`tools`	`Tool[]`	No	Tool/function definitions the model can call.
`tool_choice`	`string \| object`	No	Controls tool selection. `"auto"` by default.
`response_format`	`object`	No	Force JSON output: `{ "type": "json_object" }`.
`stop`	`string \| string[]`	No	Up to 4 stop sequences.
`seed`	`integer`	No	Best-effort deterministic output.
`user`	`string`	No	End-user identifier for abuse monitoring.
`n`	`integer`	No	Number of completions to return. Default `1`.

`Message`

type Message = {
  role: "system" | "user" | "assistant" | "tool";
  content: string | ContentPart[];   // string for text, array for multimodal
  name?: string;                      // for tool messages
  tool_call_id?: string;              // for tool response messages
};

type ContentPart =
  | { type: "text"; text: string }
  | { type: "image_url"; image_url: { url: string; detail?: "low" | "high" | "auto" } };

Response

{
  id: string;                          // unique request id
  object: "chat.completion";
  created: number;                     // unix timestamp
  model: string;                       // the model that served the request
  choices: Array<{
    index: number;
    message: {
      role: "assistant";
      content: string | null;
      tool_calls?: ToolCall[];
    };
    finish_reason: "stop" | "length" | "tool_calls" | "content_filter";
  }>;
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
}

Examples

cURL

curl https://api.throughputs.dev/v1/chat/completions \
  -H "Authorization: Bearer $THROUGHPUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="thp_live_xxx",
    base_url="https://api.throughputs.dev/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain recursion in one sentence."},
    ],
)

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

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.THROUGHPUTS_API_KEY!,
  baseURL: "https://api.throughputs.dev/v1",
});

const response = await client.chat.completions.create({
  model: "claude-3-5-sonnet",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Explain recursion in one sentence." },
  ],
});

console.log(response.choices[0].message.content);

Function calling

Pass tools and the model can decide to call them:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather in a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                },
                "required": ["city"],
            },
        },
    }],
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]
# tool_call.function.name == "get_weather"
# tool_call.function.arguments == '{"city": "Tokyo"}'

Vision (multimodal)

Models that support vision accept an array of content parts:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://..."}},
        ],
    }],
)

Errors

Status	Meaning
`400`	Malformed request body or invalid parameters.
`401`	Missing or invalid API key.
`402`	Payment required — your account is out of credit.
`404`	Unknown model slug.
`429`	Rate limit hit. See `Retry-After`.
`500` / `502` / `503`	Upstream provider error. THROUGHPUTS already retried twice.

On this page