Chat completions

Send chat requests to one endpoint using the OpenAI request shape. Two fields are always required — model and messages. Everything else is optional, and the capability fields (tools, response_format, reasoning_effort, image and file parts) only work on models that list them in GET /v1/models. Fields the API does not recognize are ignored.

POSThttps://api.astorias.ai/v1/chat/completions

Start with this minimal request — replace the braced placeholders. Tick Advanced above the example to see every optional parameter. The capability fields (tools, response_format, reasoning_effort) only work on models that list them in GET /v1/models.

# Minimal chat completion. Replace the braced placeholders.
# Every optional parameter is listed under Advanced.

curl \
  --request POST \
  --url "https://api.astorias.ai/v1/chat/completions" \
  --header "Authorization: Bearer $ASTORIAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "{huggingface-model-id}",
    "messages": [
      { "role": "user", "content": "{user-message}" }
    ]
  }'

Required

modelrequired
string

Model id from GET /v1/models or Model Garden. Unknown ids return 400 model_not_found.

messagesrequired
message[]

At least one message. Roles: system, user, assistant, tool, developer, function. Each message's content is a string or an array of parts with a type field.

Sampling and length

temperatureoptionaldefault: model default
number

Randomness of the output. Range 0 to 2.

top_poptionaldefault: model default
number

Nucleus sampling cutoff. Range 0 to 1.

top_koptionaldefault: model default
integer

Samples from the top K tokens. Integer from 1 to 200.

max_tokensoptional
integer

Minimum 1. Must not exceed the model's maximum output length. Alias: max_completion_tokens — send one of the two, not both.

max_completion_tokensoptional
integer

Same limit as max_tokens. Either field is accepted.

stopoptional
string | string[]

Generation stops when one of these strings appears. Up to 4 sequences.

noptionaldefault: 1
integer

Number of completions, 1 to 8. Each completion is billed separately.

frequency_penaltyoptionaldefault: 0
number

Discourages repeating tokens. Range -2 to 2.

presence_penaltyoptionaldefault: 0
number

Discourages introducing new topics. Range -2 to 2.

Capabilities (depend on the model)

These fields only work when the model lists them under supported_parameters in GET /v1/models. Sending one the model does not support returns 400 invalid_request — retrying the same body fails the same way, so check the catalog first.

toolsoptional
object[]

Function tools. Requires tools on the model. See Function calling.

tool_choiceoptionaldefault: auto
string | object

Controls tool use when tools are allowed: none, auto, required, or a specific function.

response_formatoptional
object

type json_object or json_schema requires structured outputs on the model. Other types are not gated. See Structured outputs.

reasoning_effortoptional
string

none, low, medium, high, xhigh, or max — but only the values the model lists. Each model supports a different subset. See Reasoning.

Image and file parts

Message parts of type image_url or file return 400 unless that model lists the matching input in the catalog. Most models accept text only.

Streaming

streamoptionaldefault: false
boolean

When true, the response is server-sent events instead of one JSON object. See below.

stream_optionsoptional
object

Streaming only. Send { include_usage: true } to append a usage frame before [DONE].

Set stream: true. The response is text/event-stream. Tokens arrive as data: frames and a completed stream ends with [DONE]. If the stream breaks after bytes have already been sent, you get one error frame and no [DONE].

# POST https://api.astorias.ai/v1/chat/completions with stream true
#
# Flags that differ from a non-stream request
#   --header Accept      text/event-stream. Tokens arrive as data: frames.
#   --no-buffer          Do not wait for a full chunk before printing (-N).
#   --include            Still prints X-Request-ID on the first bytes.
#
# Body keys that belong to streaming
#   stream               true. Response is SSE, not one JSON object.
#   stream_options       { "include_usage": true } appends a usage frame
#                        before data: [DONE]
#
# A completed stream ends with data: [DONE]. If the stream dies after
# bytes have already been sent, you get one error frame and no [DONE].
# Closing the connection still bills the prompt plus flushed tokens.

curl \
  --request POST \
  --url "https://api.astorias.ai/v1/chat/completions" \
  --header "Authorization: Bearer $ASTORIAS_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: text/event-stream" \
  --no-buffer \
  --include \
  --data '{
    "model": "{huggingface-model-id}",
    "messages": [
      { "role": "system", "content": "{system-prompt}" },
      { "role": "user", "content": "{user-message}" }
    ],
    "stream": true,
    "stream_options": { "include_usage": true },
    "temperature": 1,
    "top_p": 1,
    "max_tokens": 256
  }'

Cancelled streams are still billed

Closing the connection still bills the prompt plus whatever completion tokens were already sent. A request that fails before any work starts costs nothing. Details are in Usage and billing.

The request body may be at most 10 MB. Larger requests return 413 payload_too_large.

Response and usage

Responses follow the OpenAI shape: an id, choices[].message.content (or tool_calls when the model called a tool), and a usage object. prompt_tokens includes cached prompt tokens and completion_tokens includes reasoning tokens; when the model prices those separately they are billed at their own catalog rates.

Every response includes an X-Request-ID header. Keep it for support.