MoonCo API integration

MoonCo exposes an OpenAI-compatible API at:

https://api.moonco.one/v1

MoonCo supports the API subset documented on this page. This does not imply support for every OpenAI endpoint, parameter, or SDK feature. Undocumented behavior is outside the supported interface.

All requests use HTTPS and bearer authentication. Set your API key in the process environment:

export MOONCO_API_KEY="your-api-key"

Send it on every request as Authorization: Bearer $MOONCO_API_KEY. The examples use the production URL unless MOONCO_API_BASE_URL is set.

The SDK examples use the openai package with automatic retries disabled. JavaScript / TypeScript examples run in Node.js. See Errors and retries before adding retries.

Chat completions

POST /v1/chat/completions supports these request fields:

If an assistant response includes tool_calls, run the functions and send the assistant calls with tool results that use matching tool_call_id values in a later request. A tool-only assistant response can have null content. Validate JSON output in your application; schema conformance is not guaranteed.

max_tokens may replace max_completion_tokens; do not send both. If set, n must be 1. Successful streams include usage. stream_options with include_usage is accepted only when stream is true.

Create a response

cURL

curl --fail-with-body --silent --show-error \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/chat/completions" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "meva",
    "messages": [
      {"role": "user", "content": "Reply with a short greeting."}
    ],
    "stream": false
  }'

Python

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONCO_API_KEY"],
    base_url=os.environ.get("MOONCO_API_BASE_URL", "https://api.moonco.one/v1"),
    max_retries=0,
)

response = client.chat.completions.create(
    model="meva",
    messages=[{"role": "user", "content": "Reply with a short greeting."}],
    stream=False,
)
print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const apiKey = process.env.MOONCO_API_KEY;
if (!apiKey) throw new Error("Set MOONCO_API_KEY in the server environment.");

const client = new OpenAI({
  apiKey,
  baseURL: process.env.MOONCO_API_BASE_URL ?? "https://api.moonco.one/v1",
  maxRetries: 0,
});

const response = await client.chat.completions.create({
  model: "meva",
  messages: [{ role: "user", content: "Reply with a short greeting." }],
  stream: false,
});
console.log(response.choices[0].message.content);

Stream a response

Set stream to true to receive server-sent events.

cURL

curl --fail-with-body --silent --show-error --no-buffer \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/chat/completions" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "meva",
    "messages": [
      {"role": "user", "content": "Reply with a short greeting."}
    ],
    "stream": true
  }'

Python

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONCO_API_KEY"],
    base_url=os.environ.get("MOONCO_API_BASE_URL", "https://api.moonco.one/v1"),
    max_retries=0,
)

stream = client.chat.completions.create(
    model="meva",
    messages=[{"role": "user", "content": "Reply with a short greeting."}],
    stream=True,
)
for chunk in stream:
    print(chunk.model_dump_json())

JavaScript / TypeScript

import OpenAI from "openai";

const apiKey = process.env.MOONCO_API_KEY;
if (!apiKey) throw new Error("Set MOONCO_API_KEY in the server environment.");

const client = new OpenAI({
  apiKey,
  baseURL: process.env.MOONCO_API_BASE_URL ?? "https://api.moonco.one/v1",
  maxRetries: 0,
});

const stream = await client.chat.completions.create({
  model: "meva",
  messages: [{ role: "user", content: "Reply with a short greeting." }],
  stream: true,
});
for await (const chunk of stream) {
  console.log(JSON.stringify(chunk));
}

Each event begins with data: and contains a JSON chat-completion chunk. A successful stream ends with data: [DONE]. Read incremental text from choices[].delta.content or tool call fragments from choices[].delta.tool_calls; inspect the final choice finish reason and final usage when present. The SDKs parse these events into chunks; the streaming examples print each chunk as JSON.

Models

GET /v1/models returns the public model IDs available to the calling key.

cURL

curl --fail-with-body --silent --show-error \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/models" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}"

Python

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONCO_API_KEY"],
    base_url=os.environ.get("MOONCO_API_BASE_URL", "https://api.moonco.one/v1"),
    max_retries=0,
)

models = client.models.list()
for model in models.data:
    print(model.id)

JavaScript / TypeScript

import OpenAI from "openai";

const apiKey = process.env.MOONCO_API_KEY;
if (!apiKey) throw new Error("Set MOONCO_API_KEY in the server environment.");

const client = new OpenAI({
  apiKey,
  baseURL: process.env.MOONCO_API_BASE_URL ?? "https://api.moonco.one/v1",
  maxRetries: 0,
});

const models = await client.models.list();
for (const model of models.data) {
  console.log(model.id);
}

meva selects the latest Meva release. meva-1 selects fixed release 1. meva-1 appears here and in the account's allowed_models list. meva is a request alias and does not appear in either list. Completion responses and stream chunks return the resolved release ID, initially meva-1. Applications should not depend on the ordering of the returned list.

Chat-completion requests still accept moon-latest, moon-1, moonco-latest, moonco-v1, and moonco-medical-v1 as input aliases.

A fixed release keeps Moonco's code and settings fixed. External model weights can change. It does not guarantee identical generated text.

Account

GET /v1/account returns the authenticated account summary.

cURL

curl --fail-with-body --silent --show-error \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/account" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}"

Python

import json
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONCO_API_KEY"],
    base_url=os.environ.get("MOONCO_API_BASE_URL", "https://api.moonco.one/v1"),
    max_retries=0,
)

account = client.get("/account", cast_to=dict)
print(json.dumps(account, indent=2))

JavaScript / TypeScript

import OpenAI from "openai";

const apiKey = process.env.MOONCO_API_KEY;
if (!apiKey) throw new Error("Set MOONCO_API_KEY in the server environment.");

const client = new OpenAI({
  apiKey,
  baseURL: process.env.MOONCO_API_BASE_URL ?? "https://api.moonco.one/v1",
  maxRetries: 0,
});

const account = await client.get("/account");
console.log(JSON.stringify(account, null, 2));

The response includes the account display name, credit totals, estimated remaining credit, exhaustion state, an as_of timestamp, allowed public model IDs, and the calling key's alias and masked identifier. limits.rpm and limits.tpm report the authenticated team's current shared request and token ceilings across all of its keys. Use as_of to check how current the summary is.

Response fields

A non-streaming chat response follows the OpenAI-compatible shape:

A streaming usage chunk uses the same usage fields. Clients should ignore additional response fields they do not recognize.

Errors and retries

Before a stream starts, errors use an HTTP status and a JSON error body. A stream can fail after HTTP 200; handle stream errors and disconnects. Treat error messages as diagnostic text; do not parse them or depend on undocumented error fields. Use the HTTP status for non-streaming errors.

Use a small retry limit. A retried chat POST can start a new completion, so retry only when your application can tolerate another generation. Do not attempt to resume a disconnected stream; start a new request if that behavior is acceptable.

API-key safety

For integration support, email support@moonco.io. Include the HTTP status, request time in UTC, and request identifier if available. Do not include API keys, request content, or other secrets.

For information about data use and retention, see the Privacy Policy.