Your first request

1. Get a key

• Request access. We review each application. Once yours is approved, you sign in to the console with your email.
• In the console, add a billing profile and a payment method, and set a monthly spending limit.
• Create an API key for the model you want to call. The key is shown once, so store it somewhere safe.

A key works for one model. To call two models, create two keys.

2. Send a request

The base URL is https://api.marscompute.ai/v1. Pass your key as a bearer token.

curl --request POST \
  --url https://api.marscompute.ai/v1/chat/completions \
  --header "Authorization: Bearer $MARSCOMPUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-6-astra",
    "messages": [{"role": "user", "content": "Explain mixture-of-experts in one paragraph."}],
    "max_tokens": 256,
    "stream": false
  }'

import os
import requests

api_key = os.environ["MARSCOMPUTE_API_KEY"]
response = requests.post(
    "https://api.marscompute.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-6-astra",
        "messages": [
            {
                "role": "user",
                "content": "Explain mixture-of-experts in one paragraph.",
            }
        ],
        "max_tokens": 256,
        "stream": False,
    },
    timeout=120,
)
response.raise_for_status()
completion = response.json()
print(completion["choices"][0]["message"]["content"])

const apiKey = process.env.MARSCOMPUTE_API_KEY;
if (!apiKey) throw new Error("MARSCOMPUTE_API_KEY is required");

const response = await fetch(
  "https://api.marscompute.ai/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-6-astra",
      messages: [
        {
          role: "user",
          content: "Explain mixture-of-experts in one paragraph.",
        },
      ],
      max_tokens: 256,
      stream: false,
    }),
  },
);

if (!response.ok) {
  throw new Error("MarsCompute request failed: " + (await response.text()));
}

const completion = await response.json();
console.log(completion.choices?.[0]?.message?.content ?? completion);

The reply is a chat completion object. The answer is in choices[0].message.content, and usage holds the input and output token counts you are charged for. Every response carries an x-request-id header you can quote when asking about a request.

3. Streaming

Set "stream": true to receive the answer as server-sent events. The final event before data: [DONE] includes usage.

curl --no-buffer https://api.marscompute.ai/v1/chat/completions \
  --header "Authorization: Bearer $MARSCOMPUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-6-astra",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five in words."}]
  }'

4. Model IDs

Use the ID in the model field. GET /v1/models lists the models your workspace can use.

GPT-6 Astra accepts only the default temperature. Leave the field out when calling it.

5. Safe retries

Networks fail. To retry without paying twice, send an Idempotency-Key header with a value that is unique to the request, and reuse the same value when you retry.

curl https://api.marscompute.ai/v1/chat/completions \
  --header "Authorization: Bearer $MARSCOMPUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-4821-summary" \
  --data '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "Summarise order 4821."}]}'

• A repeat of a request that was already accepted is not run or charged again. It returns status 202 with the original request ID.
• Reusing a key with a different request body returns 409 idempotency_conflict.

6. Errors

Errors are JSON with a stable code and the request_id of the failed request.

{
  "error": {
    "message": "Request is not authorized for this model",
    "type": "marscompute_error",
    "code": "model_binding_mismatch"
  },
  "request_id": "req_3f2a9c0d1e5b4a7f8c6d2e1b0a9f8e7d"
}