Chat Completions | Smallest AI Docs

POST https://api.smallest.ai/waves/v1/chat/completions

OpenAI-compatible chat completion endpoint. Most OpenAI Chat Completions request fields are accepted and passed through to Electron verbatim. The response shape matches OpenAI’s chat.completion object.

Request

Authentication

Authorization: Bearer $SMALLEST_API_KEY

Required fields

Field	Type	Description
`model`	string	Always `"electron"`.
`messages`	array	Standard OpenAI message array. Max 200 messages. Each message: `{role, content, tool_calls?, tool_call_id?}` where `role` is `"system"`, `"user"`, `"assistant"`, or `"tool"`.

Common optional fields

Field	Type	Default	Notes
`temperature`	number ≥ 0	`1.0`	Sampling temperature.
`top_p`	number 0–1	`1.0`	Nucleus sampling.
`max_tokens`	int	model max	Cap on output tokens for this completion. The 32,768-token model ceiling is on combined input + output, so `max_tokens` is effectively `32,768 − prompt_tokens`.
`stream`	bool	`false`	When `true`, response is Server-Sent Events. See Streaming.
`stream_options.include_usage`	bool	`false`	When `true` (with `stream: true`), final SSE chunk carries the `usage` block.
`stream_options.continuous_usage_stats`	bool	`false`	When `true` (with `stream: true` and `include_usage: true`), every SSE chunk carries a `usage` block with the token counts so far. No effect without `include_usage`.
`stop`	string \| array of strings	-	Up to 4 stop sequences.
`seed`	int	random	Best-effort determinism.
`response_format`	object	-	`{"type":"text"}` (default) or `{"type":"json_object"}`.
`tools`	array	-	Standard OpenAI function-calling tools array. Max 64 entries. See Tool Calling.
`tool_choice`	string \| object	`"auto"`	`"auto"`, `"required"`, `"none"`, or `{"type":"function","function":{"name":"…"}}`.
`logit_bias`	object	-	Per-token id biases.
`logprobs`	bool	`false`	Return log-probabilities.
`top_logprobs`	int 0–20	-	Top-N log-probs (requires `logprobs: true`).
`presence_penalty`, `frequency_penalty`	number −2 to 2	`0`	Standard OpenAI knobs.

Unrecognized parameters not in the supported set are accepted by the schema but may be ignored by the model. See Supported Parameters for the full passthrough table.

Explicitly rejected fields

Field	Why
`n > 1`	Cost amplification with no use case in v1.
`prompt_logprobs`	Response-size amplification with no billing impact.

Sending either returns HTTP 400 with invalid_request_error.

Response

Non-streaming (default)

Standard OpenAI chat.completion object:

{
  "id": "chatcmpl-a670053f3ab2ed8f",
  "object": "chat.completion",
  "created": 1740000000,
  "model": "electron",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you today?",
        "tool_calls": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

`usage` block

Field	Description
`prompt_tokens`	Total input tokens (cached + uncached).
`prompt_tokens_details.cached_tokens`	Subset of `prompt_tokens` served from prefix cache. Billed at the discounted rate. See Prefix Caching.
`completion_tokens`	Generated output tokens.
`total_tokens`	`prompt_tokens + completion_tokens`.

`finish_reason`

Value	Meaning
`"stop"`	Natural stop (end token or `stop` sequence hit).
`"length"`	`max_tokens` reached.
`"tool_calls"`	The model returned function calls; act on them and continue the conversation.
`"content_filter"`	Content blocked.

Streaming

When stream: true, the response is text/event-stream SSE. See Streaming for chunk format and example consumer code.

Errors

Errors use the OpenAI-style envelope. Validation failures also include a details array with per-field reasons:

{
  "error": {
    "message": "Invalid input data",
    "type": "invalid_request_error",
    "param": null,
    "code": null,
    "details": [
      { "code": "custom", "message": "n > 1 is not supported", "path": ["n"] }
    ],
    "request_id": "9db74058-2421-4793-8796-b2629ff3eb1c"
  }
}

Field	Description
`error.message`	Human-readable summary.
`error.type`	What went wrong. See the table below.
`error.param`	The request field at fault, such as `model`, when there is one. Otherwise `null`.
`error.code`	`rate_limit_exceeded` on rate-limit errors, `insufficient_quota` when credits run out. Otherwise `null`.
`error.details`	Present on schema-validation failures. Array of `{code, message, path}` entries naming the offending fields. Use the `path` array to highlight the bad field in your client.
`error.request_id`	Unique trace ID. Always include it in support tickets. Also returned as the `X-Request-Id` response header.

Status	`error.type`	When
400	`invalid_request_error`	Validation failed, the model isn’t available, or the context length was exceeded.
400	`insufficient_quota`	Your credits are used up. Recharge to continue.
401	-	Missing or invalid API key. See the note below.
403	`permission_error`	Your plan doesn’t include Electron, or your organization’s billing is blocked.
429	`requests`	You hit your requests-per-minute limit.
429	`concurrency`	Too many requests in flight at once.
500	`server_error`	Unexpected server error. Retry with backoff.
502	`upstream_error`	The model is unavailable. Retry with backoff.
503	`upstream_overloaded`	The model is overloaded. Retry with backoff.
503	`service_unavailable`	Electron is temporarily unavailable. Retry after `Retry-After` seconds when the header is present.

Authentication is checked before the request reaches Electron, so a missing or invalid API key returns 401 with a short body such as {"error": "unauthorized"}, not the envelope above. An access token (wat_…) isn’t accepted on this endpoint and returns 403 with {"error": "forbidden"}; use an API key. For these, check the status code, not the body.

Response headers

Header	When
`X-Request-Id`	On every response. Same value as `error.request_id`.
`Retry-After`	On `429` and some `503` responses. Seconds to wait before retrying. A `429` without it means your plan doesn’t include this API, so retrying won’t help.
`x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, `x-ratelimit-reset-requests`	When your plan has a requests-per-minute limit. `reset` is the time until the limit is fully free again, such as `12s`.

Examples

Minimal

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.smallest.ai/waves/v1",
    api_key=os.environ["SMALLEST_API_KEY"],
)
resp = client.chat.completions.create(
    model="electron",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain prefix caching in one sentence."},
    ],
)
print(resp.choices[0].message.content)

Multi-turn

messages = [
    {"role": "system", "content": "You are a customer-support agent."},
    {"role": "user", "content": "I want to change my plan."},
    {"role": "assistant", "content": "Sure — which plan are you on right now?"},
    {"role": "user", "content": "Standard, and I want to upgrade to Enterprise."},
]
resp = client.chat.completions.create(model="electron", messages=messages)

JSON object output

resp = client.chat.completions.create(
    model="electron",
    messages=[
        {"role": "system", "content": "Reply with strict JSON."},
        {"role": "user", "content": "List three Indian state capitals as {\"capitals\": [...]}"},
    ],
    response_format={"type": "json_object"},
    temperature=0,
)