Chat completions

POST /v1/chat/completions is the endpoint for chat models. The request body and the response follow the OpenAI Chat Completions API: the OpenAI SDKs use it with no special setup.

POST https://api.realmoon.ai/v1/chat/completions

• Authentication: an sk-moon-… key with the inference scope (see Authentication).
• Body: JSON (Content-Type: application/json).
• Response: a chat.completion object, or an SSE stream of chat.completion.chunk chunks with "stream": true.
• Billing: pay as you go, from the wallet of the key’s workspace (see Costs).

Example#Link to the Example section

curl https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [
          {"role": "system", "content": "Answer in one sentence."},
          {"role": "user", "content": "What is an API?"}
        ],
        "max_tokens": 300,
        "temperature": 0.3
      }'

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.realmoon.ai/v1", api_key=os.environ["MOONAI_API_KEY"])

response = client.chat.completions.create(
    model="anthropic/claude-haiku-4.5",
    messages=[
        {"role": "system", "content": "Answer in one sentence."},
        {"role": "user", "content": "What is an API?"},
    ],
    max_tokens=300,
    temperature=0.3,
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.realmoon.ai/v1', apiKey: process.env.MOONAI_API_KEY });

const response = await client.chat.completions.create({
  model: 'anthropic/claude-haiku-4.5',
  messages: [
    { role: 'system', content: 'Answer in one sentence.' },
    { role: 'user', content: 'What is an API?' },
  ],
  max_tokens: 300,
  temperature: 0.3,
});
console.log(response.choices[0].message.content);

Parameters#Link to the Parameters section

The body is a JSON object. The parameters in the table are passed on to the model, except provider and transforms, which are checked separately (see Provider preferences); any other parameter is dropped without an error (see Ignored parameters). A model can reject a parameter it does not support (400 unsupported_parameter).

Sampling settings depend on the model: a model may ignore some of them.

Provider preferences#Link to the Provider preferences section

The same model can be served by several providers. The provider object narrows down or orders that choice; it never widens it.

• Lists hold 64 names at most.
• A default value (allow_fallbacks: true, zdr: false, data_collection: "allow", empty list) is ignored.
• Any other key, or an invalid value, is rejected with 400 unsupported_parameter and a param that names it (for example provider.foo).
• The maximum price passed on is never higher than the model’s price in /v1/models: a preference never gets the request served at a higher price than the hold covers.
• Not every model supports these preferences. On a model that does not, for example a model hosted by Moon AI, an active preference is rejected with 400 unsupported_parameter (param: "provider").
• The data_collection and zdr commitments are the ones providers declare; Moon AI does not verify them.

transforms: ["middle-out"] shortens the middle of a conversation that is too long for the model’s context window. Any other value is rejected (400 unsupported_parameter, param: "transforms"), as is middle-out on a model that does not support provider preferences.

Messages#Link to the Messages section

messages is an array of message objects, from oldest to newest.

A content array holds parts:

Any other part is rejected with 400 unsupported_content, in particular:

• a file referenced by its ID (file_id): send its content in file_data instead;
• a video;
• audio sent as a file: use an input_audio part;
• audio on a model whose audio price is not known.

Response#Link to the Response section

Without streaming, the response is a chat.completion object.

{
  "id": "gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a",
  "object": "chat.completion",
  "created": 1793577600,
  "model": "anthropic/claude-haiku-4.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An API is an interface that lets two pieces of software exchange data."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

The response never includes the cost or the provider that served the model: provider, system_fingerprint, native_finish_reason and the cost fields of usage are removed.

Response headers#Link to the Response headers section

Streaming#Link to the Streaming section

With "stream": true, the response arrives as Server-Sent Events (Content-Type: text/event-stream) in the OpenAI format. The HTTP status (200) and the headers go out with the first byte.

curl -N https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [{"role": "user", "content": "Write a haiku about the Moon."}],
        "stream": true
      }'

stream = client.chat.completions.create(
    model="anthropic/claude-haiku-4.5",
    messages=[{"role": "user", "content": "Write a haiku about the Moon."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

const stream = await client.chat.completions.create({
  model: 'anthropic/claude-haiku-4.5',
  messages: [{ role: 'user', content: 'Write a haiku about the Moon.' }],
  stream: true,
});
for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) console.log('\n', chunk.usage);
}

Event format#Link to the Event format section

Each event is a data: line followed by a JSON object, then a blank line. The last event is data: [DONE]. Lines that start with : are comments.

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[{"index":0,"delta":{"role":"assistant","content":"Pale"},"finish_reason":null}]}

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[{"index":0,"delta":{"content":" moon above the rooftops"},"finish_reason":null}]}

: keep-alive

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[],"usage":{"prompt_tokens":16,"completion_tokens":21,"total_tokens":37}}

data: [DONE]

• The chunk that carries usage always arrives, even without stream_options: check that choices is not empty before reading it.
• : keep-alive comments arrive while the model is thinking, to keep the connection open. The SDKs ignore them.
• When Moon Blur replaced a value, it is put back in the text, the reasoning and the tool arguments, even when a placeholder is split across two chunks.
• If the stream is cut on our side or at the provider, a final data: {"error": {"message": "upstream stream interrupted", "type": "server_error", "code": "upstream_error"}} event signals that the response is incomplete. The SDKs raise it as an error during iteration.
• A stream lasts one hour at most, and it is cut if the model sends nothing for 5 minutes.
• The cost is settled when the stream ends. If your client closes the connection before that, the request is settled at the cost the provider reports for what it produced, or keeps part of its hold (see Settlement).

Tools (function calling)#Link to the Tools (function calling) section

Only tools of type function, run by your own program, are accepted. A tool of any other type (run by the provider, such as a web search) is rejected with 400 unsupported_parameter and param: "tools".

curl https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [{"role": "user", "content": "What is the weather like in Lyon?"}],
        "tools": [{
          "type": "function",
          "function": {
            "name": "get_weather",
            "description": "Current weather in a city",
            "parameters": {
              "type": "object",
              "properties": {"city": {"type": "string"}},
              "required": ["city"]
            }
          }
        }],
        "tool_choice": "auto"
      }'

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather in a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]
messages = [{"role": "user", "content": "What is the weather like in Lyon?"}]

first = client.chat.completions.create(model="anthropic/claude-haiku-4.5", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)

messages.append(first.choices[0].message)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps({"city": args["city"], "sky": "clear", "temperature": 18})})

final = client.chat.completions.create(model="anthropic/claude-haiku-4.5", messages=messages, tools=tools)
print(final.choices[0].message.content)

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Current weather in a city',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
  },
}];
const messages = [{ role: 'user', content: 'What is the weather like in Lyon?' }];

const first = await client.chat.completions.create({ model: 'anthropic/claude-haiku-4.5', messages, tools });
const call = first.choices[0].message.tool_calls[0];
const args = JSON.parse(call.function.arguments);

messages.push(first.choices[0].message);
messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify({ city: args.city, sky: 'clear', temperature: 18 }) });

const final = await client.chat.completions.create({ model: 'anthropic/claude-haiku-4.5', messages, tools });
console.log(final.choices[0].message.content);

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_01",
      "type": "function",
      "function": { "name": "get_weather", "arguments": "{\"city\":\"Lyon\"}" }
    }
  ]
}

• Not every model can call tools.
• Arguments (function.arguments) arrive as a JSON string. When Moon Blur masked a value, it is put back in the arguments, which remain valid JSON.
• finish_reason is tool_calls when the model is waiting for the results of your functions.

Images and files#Link to the Images and files section

A model that reads images accepts image_url parts in a user message.

curl https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [{
          "role": "user",
          "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
          ]
        }]
      }'

import base64

with open("photo.jpg", "rb") as f:
    data_url = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="anthropic/claude-haiku-4.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": {"url": data_url}},
        ],
    }],
)
print(response.choices[0].message.content)

import fs from 'node:fs';

const dataUrl = 'data:image/jpeg;base64,' + fs.readFileSync('photo.jpg').toString('base64');

const response = await client.chat.completions.create({
  model: 'anthropic/claude-haiku-4.5',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'Describe this image.' },
      { type: 'image_url', image_url: { url: dataUrl } },
    ],
  }],
});
console.log(response.choices[0].message.content);

• An image at an https:// URL is fetched by the model provider, not by Moon AI.
• On OpenAI models, an image with no detail (or with auto) is sent with detail: "high".
• For most models, a PDF sent in a file part is read by the model if it can read files; otherwise, its text is extracted before sending.
• A request’s hold takes its attachments into account. An image for a model whose image pricing is not known, a PDF file or an audio clip can be held up to the size of the context window: the hold can be high, but it is released after the response (see Costs).

Moon Blur reads only text: images, files and audio are sent as is.

Reasoning#Link to the Reasoning section

Reasoning models accept reasoning_effort or the reasoning object, depending on their family. When the model returns its reasoning, it arrives in a field of the message or of the stream chunk (reasoning or reasoning_content, depending on the model). Reasoning tokens are output tokens: they count in usage and toward the output limit.

Response length#Link to the Response length section

• With max_tokens (or max_completion_tokens), the model produces no more than this value, reasoning included. A larger reasoning.max_tokens budget is brought down to this value.
• Without max_tokens, the response gets at least 4,096 output tokens (fewer if the model’s limit is lower). If the balance or a spend cap cannot cover that size, the request is refused (402) rather than served in a few words. Beyond that, the limit rises up to the model’s own limit (16,384 tokens at most), as long as a small share of what is left in the balance and the caps covers it, to leave room for concurrent requests. It also leaves room for the input within the context window.
• For an OpenAI reasoning model called directly, the limit is sent as max_completion_tokens.

Setting max_tokens makes the hold smaller and more predictable. We recommend it when many requests run at the same time.

Ignored parameters#Link to the Ignored parameters section

These parameters are removed before sending, without an error: store, metadata, service_tier, modalities, audio, prediction, web_search_options, plugins, stream_options (the server itself requests usage at the end of the stream) and any parameter that is not in the parameter table. So the store parameter cannot ask the provider to keep your requests.

Errors#Link to the Errors section

Key and rate errors, common to the whole API, are in Errors. Model refusals are passed on without the provider’s name, links or internal IDs.

See also#Link to the See also section

• Models: IDs and prices.
• Balance and request cost: read what a chat request cost.
• Limits: rate limits, timeouts and retries.