Chat Completions
POST /v1/chat/completions — send a conversation, receive a
completion. OpenAI-compatible request and response shapes.
Request
curl https://api.astrodyne.ai/v1/chat/completions \
-H "Authorization: Bearer $ASTRODYNE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [{"role": "user", "content": "Hello"}]
}'
Request fields
| Field | Type | Notes |
|---|---|---|
model | string, required | A canonical model ID from /v1/models. |
messages | array, required | Ordered messages with role (system, developer, user, assistant, tool) and content. |
stream | boolean | Set true for SSE streaming. |
temperature | number, 0–2 | Sampling temperature. |
top_p | number, 0–1 | Nucleus sampling. |
max_tokens | integer ≥ 1 | Your billable output ceiling — see below. Defaults to 1,024 when omitted; requests above 32,768 are rejected. |
max_completion_tokens | integer ≥ 1 | Accepted as an alias for the billable output ceiling. |
stop | string or array | Stop sequence(s). |
presence_penalty, frequency_penalty | number, −2–2 | Repetition controls. |
tools, tool_choice | array / string | Tool definitions in the OpenAI shape; support depends on the selected model. |
response_format | object | For example {"type": "json_object"}; support depends on the selected model. |
seed | integer | Best-effort determinism. |
user | string | Your own end-user identifier. |
400 that names the
parameter — they are never silently dropped. This makes typos loud instead of
mysterious.
What max_tokens guarantees
max_tokens is the ceiling on what you can be billed
for output on a request. It is sent to the model as the requested output cap,
and we bill no more than it regardless of what comes back.
It is not a promise that the model will stop at exactly that
many tokens. Some models — reasoning models in particular — return more output
than the cap they were given. When that happens the excess is
absorbed by Astrodyne and never billed to you:
billable_output_tokens never exceeds the max_tokens
you sent. Where the provider reports it, the raw figure is recorded separately
and appears on the usage API beside the billable
one, so you see both numbers rather than a single figure that hides the
difference.
Two consequences worth stating plainly. Your bill is bounded by the number you
send. And a response may contain more text than the cap implies, so treat
max_tokens as a cost control rather than as a length guarantee.
Response
{
"id": "chatcmpl-…",
"object": "chat.completion",
"model": "YOUR_MODEL_ID",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "Hello! How can I help?" },
"finish_reason": "stop"
}],
"usage": { "prompt_tokens": 9, "completion_tokens": 7, "total_tokens": 16 }
}
usage is the token accounting your request settles against;
the retail charge appears with the request in the
Request Explorer. The
X-Astrodyne-Request-Id header carries the
public request ID.
Idempotent retries
Send an Idempotency-Key header (any unique string) with a
non-streaming request to make retries safe: if the same key and an identical
request body arrive again, Astrodyne returns the recorded outcome instead of
executing — and never bills twice. Replayed responses include an
X-Astrodyne-Idempotent-Replay: true header. Streaming requests
cannot be replayed.
Errors
Failures use the standard error shape with customer-safe messages — never raw internal detail.