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:
model: usemevaor a model ID returned byGET /v1/models;messages: one or more orderedsystem,user,assistant, ortoolmessages. Usercontentcan be a string or a nonempty array of{"type":"text","text":"..."}parts;stream:falsefor one JSON response ortruefor server-sent event chunks;max_completion_tokens: positive output-token ceiling up to 32,768;temperature: number from0through2;top_p: number greater than0through1;stop: one string or an array of strings;tools: OpenAI-style function definitions;tool_choicemay beautoornone;response_format: an object withtypeset tojson_objectorjson_schemafor JSON output. Schema mode also requires ajson_schemaobject withnameandschema.
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:
id: MoonCo request identifier;object,created, andmodel: response metadata;choices[].index: choice position;choices[].message.role,choices[].message.content, and optionalchoices[].message.tool_calls: generated message; content can be null for tool calls;choices[].finish_reason: why generation stopped;usage.prompt_tokens,usage.completion_tokens, andusage.total_tokens: token counts;usage.billable_cost_microusd: the request's MoonCo billable cost as a whole number of millionths of one US dollar.
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.
400: correct the request before trying again.401or403: check the key and its access, then stop automatic retries.404: check the path and public model ID.429: check available credit and limits. If credit is exhausted, resolve it before retrying. For temporary rate limits, wait before trying again and honorRetry-Afterwhen supplied.5xx, connection failure, or timeout: retry with capped exponential backoff and jitter.
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
- Keep keys in a secret manager or protected process environment, not source code.
- Never place a key in a URL, query string, browser bundle, log, screenshot, or support message.
- Send keys only to the MoonCo HTTPS API base URL.
- Use separate keys for separate applications when issued, and revoke a key that may be exposed.
- Do not embed a key in software distributed to end users.
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.