Create a chat completion

curl --request POST \
  --url https://api.aurous-labs.com/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "model": "aurous-grow-2.0-pro",
  "messages": [
    {
      "content": "<string>",
      "name": "<string>",
      "tool_call_id": "<string>"
    }
  ],
  "max_tokens": 2,
  "temperature": 1,
  "top_p": 0.5,
  "stream": true,
  "stream_options": {},
  "tools": [
    {
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": [
            "city"
          ]
        }
      }
    }
  ],
  "tool_choice": {},
  "response_format": {},
  "seed": 123,
  "stop": {},
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "logprobs": true,
  "top_logprobs": 10
}
'

{
  "id": "cmp_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "created": 1731948000,
  "model": "aurous-grow-2.0-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": {},
        "tool_calls": [
          {
            "id": "call_01HXM...",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Tokyo\"}"
            }
          }
        ]
      }
    }
  ],
  "usage": {
    "prompt_tokens": 200,
    "completion_tokens": 600,
    "total_tokens": 850,
    "credits_charged": 0.2856,
    "breakdown": {
      "input_credits": 0.0006,
      "output_credits": 0.27,
      "model": "aurous-grow-2.0-pro",
      "pricing_version": 7,
      "reasoning_credits": 0.015
    },
    "reasoning_tokens": 50
  },
  "status": "completed",
  "error": {
    "code": "chat_provider_unavailable",
    "type": "server_error",
    "message": "Provider request failed."
  }
}

Chat completions

Create a chat completion

OpenAI-compatible chat completion. Supports streaming (stream: true returns text/event-stream SSE), function calling (tools / tool_choice), multimodal input (image_url / video_url content parts), reasoning_effort, and structured output (response_format). Pricing: credits are debited from team balance at completion, snapshotted to the per-model pricing version that was active when the credit hold was placed.

Idempotency-Key is honored on non-streamed requests only (24h replay window). Streamed requests echo Aurous-Idempotency-Status: ignored_streaming and emit a warning frame as the first SSE data line; use stream=false for at-most-once semantics.

Image and video rates are frozen per Aurous-Version: customers pinned to an older version see the rate card that was current when their version shipped, so price changes are never silently retroactive. Chat and embedding rates are NOT frozen per Aurous-Version — they track the most recently published rate version for each model, because LLM provider economics shift on weekly cadence. The receipt echoed on every chat / embedding response carries the exact rate that applied at dispatch time, so audit trails remain stable.

POST

chat

completions

Create a chat completion

curl --request POST \
  --url https://api.aurous-labs.com/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "model": "aurous-grow-2.0-pro",
  "messages": [
    {
      "content": "<string>",
      "name": "<string>",
      "tool_call_id": "<string>"
    }
  ],
  "max_tokens": 2,
  "temperature": 1,
  "top_p": 0.5,
  "stream": true,
  "stream_options": {},
  "tools": [
    {
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": [
            "city"
          ]
        }
      }
    }
  ],
  "tool_choice": {},
  "response_format": {},
  "seed": 123,
  "stop": {},
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "logprobs": true,
  "top_logprobs": 10
}
'

{
  "id": "cmp_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "created": 1731948000,
  "model": "aurous-grow-2.0-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": {},
        "tool_calls": [
          {
            "id": "call_01HXM...",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Tokyo\"}"
            }
          }
        ]
      }
    }
  ],
  "usage": {
    "prompt_tokens": 200,
    "completion_tokens": 600,
    "total_tokens": 850,
    "credits_charged": 0.2856,
    "breakdown": {
      "input_credits": 0.0006,
      "output_credits": 0.27,
      "model": "aurous-grow-2.0-pro",
      "pricing_version": 7,
      "reasoning_credits": 0.015
    },
    "reasoning_tokens": 50
  },
  "status": "completed",
  "error": {
    "code": "chat_provider_unavailable",
    "type": "server_error",
    "message": "Provider request failed."
  }
}

Authorizations

X-Api-Key

string

header

required

Your team API key (starts with al_live_).

Headers

Aurous-Idempotency-Status

string

Echoed on the response. ignored_streaming when stream=true (idempotency does not apply); otherwise reflects the interceptor decision.

Idempotency-Key

string

Stripe-style idempotency key. Honored only when stream=false. Same key + same canonical-JSON body returns the cached response with Aurous-Idempotent-Replayed: true. Same key + different body returns 409 idempotency_key_in_use. Replay window is 24 hours.

Aurous-Version

string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-05-15"

Body

application/json

model

string

required

Public model slug from GET /v1/models. Example: aurous-grow-2.0-pro.

Maximum string length: 128

Example:

"aurous-grow-2.0-pro"

messages

object[]

required

Conversation messages, ordered oldest → newest. 1-200 messages.

Show child attributes

max_tokens

number

Maximum tokens to generate. Defaults to the model’s default_max_output_tokens. Requests with max_tokens > the model’s max_output_tokens_hard_cap return 400 max_tokens_exceeds_hard_cap.

Required range: x >= 1

temperature

number

Required range: 0 <= x <= 2

top_p

number

Required range: 0 <= x <= 1

stream

boolean

If true, response is text/event-stream (SSE) with OpenAI-shaped chunks. When streaming, Idempotency-Key is ignored and a warning frame is emitted in the first chunk; use stream=false for at-most-once semantics.

stream_options

object

OpenAI-compatible stream options. When stream: true, include_usage: true (the default on Aurous Labs) causes the final non-[DONE] SSE frame to carry the usage block with token counts + credits_charged. Set include_usage: false to suppress (matches OpenAI behavior when the flag is omitted on their side). Ignored when stream: false.

tools

object[]

Show child attributes

tool_choice

object

Function-calling routing: auto | none | {type:"function", function:{name}}. required is NOT supported and returns 400 tool_choice_required_unsupported.

response_format

object

Structured output. {type:"text"|"json_object"|"json_schema", json_schema?:{...}}. For json_schema, the schema must be ≤10KB JSON-stringified and ≤5 levels deep, else 400 response_format_too_large / response_format_too_deep.

reasoning_effort

enum<string>

Reasoning depth for reasoning-capable models. Higher values increase latency + token cost (reasoning tokens billed separately at the model’s output rate).

Available options:

minimal,

low,

medium,

high

seed

number

Random seed for reproducibility (when supported by the model).

stop

object

Up to 4 stop sequences (string or array of strings; each ≤200 chars).

presence_penalty

number

Required range: -2 <= x <= 2

frequency_penalty

number

Required range: -2 <= x <= 2

logprobs

boolean

Return log-probabilities for output tokens.

top_logprobs

number

Required range: 0 <= x <= 20

Response

Chat completion. Content type depends on stream: application/json for stream:false (full response body); text/event-stream for stream:true (SSE).

string

required

Opaque chat-completion id.

Example:

"cmp_01HXMQ7Z3K8Y2ABCDEFGHJKM"

object

enum<string>

required

Available options:

chat.completion

created

number

required

Unix timestamp (seconds).

Example:

1731948000

model

string

required

Aurous model slug used.

Example:

"aurous-grow-2.0-pro"

choices

object[]

required

Always exactly 1 entry in v1.0.

Show child attributes

usage

object

required

Show child attributes

status

enum<string>

required

Aurous extension: terminal state of the chat completion. completed is the normal happy path. in_progress means the request is still being processed (only possible when polling GET /:id during a streamed request). failed means the provider or platform errored — see error for the typed reason. cancelled means a cancel was requested or the client disconnected.

Available options:

completed,

in_progress,

failed,

cancelled

Example:

"completed"

error

object

Aurous extension: present only when status is failed or cancelled (in addition to the main error response when applicable). Echoes the typed error envelope shape so customers can branch on error.code without parsing string messages.

Show child attributes

Example:

{
  "code": "chat_provider_unavailable",
  "type": "server_error",
  "message": "Provider request failed."
}

Pricing Retrieve a stored chat completion