Build with MarsCompute

The API follows the OpenAI chat completions format. If you have a client for that, you need a new base URL and a MarsCompute key.

Start here

Start here Quickstart Create an account, add credit, make a key and send your first request with the OpenAI SDK you already use. About five minutes. Start the Quickstart

Keys and access

  • Sign up with your work email and a password, or with Google, and confirm the address with the emailed code. Your workspace opens as soon as you are verified.
  • In the console, add your billing details and buy credit by card, from $10. Each request is paid from your credit.
  • Create an API key. The key is shown once, so store it somewhere safe.

One key works for every model: name the model in each request. You can limit a key to one model when you create it.

Browsers may call the API too. A key in a web page can be read by anyone who loads it, so call the API from your own server, or give a page a key limited to one model with a monthly spending limit.

Send a request

The base URL is https://api.marscompute.ai/v1. Pass your key as a bearer token. With an OpenAI SDK, set the SDK's base URL to that address and use your MarsCompute key.

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

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.

With the Vercel AI SDK

Use its OpenAI-compatible provider. To get JSON that follows a schema, with generateObject or an output setting, also set supportsStructuredOutputs: true. Without it the SDK does not send your schema, and the answer may not match it.

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateObject } from "ai";
import { z } from "zod";

const marscompute = createOpenAICompatible({
  name: "marscompute",
  baseURL: "https://api.marscompute.ai/v1",
  apiKey: process.env.MARSCOMPUTE_API_KEY,
  supportsStructuredOutputs: true,
});

const { object } = await generateObject({
  model: marscompute.chatModel("qwen3-30b-a3b-instruct-2507"),
  schema: z.object({ city: z.string(), population: z.number() }),
  prompt: "Give Singapore's city name and approximate population.",
});
console.log(object);

With @ai-sdk/openai instead, create each model with .chat("model-id"). Its default calls OpenAI's Responses API, which MarsCompute does not offer.

Streaming

Set "stream": true to receive the answer as server-sent events. The final event before data: [DONE] includes usage. A stream that breaks off after the answer has started, on the provider's side or at the platform's time limit, ends instead with an error event, data: {"error": …}, and no [DONE]. The usage you are charged for comes before it.

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

Model IDs

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

Model Model ID Status
Qwen-SEA-LION-v4.5-27B-IT qwen-sea-lion-v4.5-27b Live
Kimi K3 k3 Live
Kimi K2.7 Code kimi-k2.7-code Live
Kimi K2.6 kimi-k2.6 Live
GLM-5.3 glm-5.3 Live
GLM-5.3 Flash glm-5.3-flash Live
GLM-5.2 glm-5.2 Live
GLM-5.1 glm-5.1 Live
GLM-5 Turbo glm-5-turbo Live
DeepSeek V4 Pro deepseek-v4-pro Live
DeepSeek V4.1 Flash deepseek-v4.1-flash Live
MiniMax M3 minimax-m3 Live
MiniMax M3.1 Flash minimax-m3.1-flash Live
Qwen3.8-27B qwen3.8-27b Live
Qwen3.6-35B-A3B qwen3.6-35b-a3b Live
Qwen3-30B-A3B-Instruct-2507 qwen3-30b-a3b-instruct-2507 Live
MiMo-V2.6-Flash mimo-v2.6-flash Live
Gemma 3 27B gemma-3-27b-it Live
Hermes 4 405B hermes-4-405b Live
Nemotron 3 Ultra 550B-A55B nemotron-3-ultra-550b-a55b Live
Nemotron 3.5 Lightning nemotron-3.5-lightning Live
MiniMax H3 (video) minimax-h3 Live
Pika H3 Flex (video) pika-h3-flex Live

Most text models reason before they answer and refuse a max_tokens below 2,048. See Reasoning and tokens.

Reasoning and tokens

You pay for the tokens in each response's usage. They can be more than the text you sent and received, for two reasons.

Reasoning counts as output

Most text models reason before they answer, and they refuse a max_tokens below 2,048, except MiniMax M3.1 Flash, which can use 2,000 or more. Kimi K3 reasons too, without showing it: about half of its output tokens in our tests. DeepSeek V4.1 Flash may reason. Neither has a minimum. Qwen3-30B-A3B-Instruct-2507, MiMo-V2.6-Flash, Gemma 3 27B and Hermes 4 405B answer without reasoning first. Leaving max_tokens out gives the default of 65,536, which is also the most any text model accepts; a long prompt lowers the default to the room left in the model's context.

Reasoning can use all of max_tokens, even the 2,048 minimum, and leave the answer empty. The response then has finish_reason "length" and no content, and its tokens are still charged. This can happen even for short answers. Leave max_tokens out or set it higher, and retry such a response with a larger limit.

Some models add input tokens

Each model wraps your messages in its own chat format, and some add a built-in system prompt. Both count as input on every request. In our tests a five-word message counted 10 to 22 input tokens on most models, and more on these:

Model Input tokens
MiniMax M3.1 Flash About 200
MiniMax M3 About 180
Kimi K3 About 90
Qwen3.8-27B 54 to 67

Generate a video

Video models work as jobs. Create one with POST /v1/videos, which needs an Idempotency-Key header, then poll GET /v1/videos/{id} until its status is completed, and download the MP4. A clip usually takes 5 to 13 minutes. The video can be downloaded for 90 days after the job finishes; after that the job’s status is expired and the video is deleted. Reference images, clips and audio you send are deleted 90 days after the last job that used them.

curl https://api.marscompute.ai/v1/videos \
  --header "Authorization: Bearer $MARSCOMPUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: launch-teaser-1" \
  --data '{
    "model": "minimax-h3",
    "prompt": "A slow push-in on a neon sign that reads OPEN, at night, in the rain",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

The reply is the job, with its id and status pending. Set JOB_ID to that id, check the job every 15 to 30 seconds, then fetch the clip:

curl https://api.marscompute.ai/v1/videos/$JOB_ID \
  --header "Authorization: Bearer $MARSCOMPUTE_API_KEY"

curl --output clip.mp4 https://api.marscompute.ai/v1/videos/$JOB_ID/content \
  --header "Authorization: Bearer $MARSCOMPUTE_API_KEY"

The same three steps in Python, with requests:

import os
import time
import uuid

import requests

API = "https://api.marscompute.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['MARSCOMPUTE_API_KEY']}"}

# 1. Create the job. The Idempotency-Key makes a retry safe: it never makes a second job.
response = requests.post(
    f"{API}/videos",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "minimax-h3",
        "prompt": "A slow push-in on a neon sign that reads OPEN, at night, in the rain",
        "duration": 5,           # seconds
        "aspect_ratio": "16:9",  # 16:9, 9:16 or 1:1
        "generate_audio": True,  # False for a silent clip
    },
    timeout=60,
)
response.raise_for_status()
job = response.json()

# 2. Wait until it is done. A clip usually takes 5 to 13 minutes.
while job["status"] in ("pending", "in_progress"):
    time.sleep(15)
    job = requests.get(f"{API}/videos/{job['id']}", headers=headers, timeout=30).json()
if job["status"] != "completed":
    raise SystemExit(f"The video {job['status']}: {job}")

# 3. Download the MP4.
video = requests.get(f"{API}/videos/{job['id']}/content", headers=headers, timeout=300)
video.raise_for_status()
with open("video.mp4", "wb") as file:
    file.write(video.content)
print("Saved video.mp4")
  • MiniMax H3 makes 2K clips of 5 to 15 seconds in 16:9, 9:16 or 1:1. Set generate_audio to false for a silent clip.
  • To animate an image, give it as the first frame, the last frame or both in frame_images, as a PNG or JPEG of up to 4 megapixels in a base64 data URL: {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}, "frame_type": "first_frame"}. A frame in another shape than the clip is cropped about its centre to the clip's shape.
  • You pay for each second delivered and for each frame image; see Pricing. A job that fails or is cancelled is not charged. Each job holds 30 seconds' worth of credit until it finishes.

Make a video from references

Pika H3 Flex (pika-h3-flex) makes a 3 to 15 second clip with sound from a prompt and 1 to 12 references by URL: up to 9 images, 3 videos and 3 audio clips, at least one image or video. Name them in the prompt as Image 1, Video 1 and so on, in the order you send them. It answers Pika's own request shape, with your MarsCompute key in X-API-Key:

curl https://api.marscompute.ai/v1/media/pika/pika-h3-flex/reference-to-video \
  --header "X-API-Key: $MARSCOMPUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "The character from image 1 dances in the room from image 2, following the moves in video 1",
    "duration": 5,
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "references": [
      { "type": "image", "url": "https://example.com/character.png" },
      { "type": "image", "url": "https://example.com/room.jpg" },
      { "type": "video", "url": "https://example.com/moves.mp4" }
    ]
  }'

The reply is {"id": ..., "status": "queued"}. Check GET /v1/media/jobs/{id} until status is completed; its output.video.url downloads the MP4 for an hour, and GET /v1/media/jobs/{id}/content gives a fresh one. DELETE /v1/media/jobs/{id} erases the video and the prompt. The same model also works at /v1/videos, with references in input_references as image_url, video_url or audio_url entries.

  • resolution is 480p, 768p (the default), 1080p, 2k or 4k (the last three are made at 768p and upscaled once); aspect_ratio is one of 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16 and 9:21, and auto gives 16:9; seed makes a clip repeatable. The clip runs a little past whole seconds, on the model's frame grid (5 s is 5.17 s at 24 fps), and you pay for the seconds you asked for.
  • References are fetched from public HTTPS URLs when the job starts: images PNG, JPEG or WebP of up to 40 megapixels and between 1:4 and 4:1; video and audio clips of 2 to 15 seconds, at most 15 seconds of each kind in all; files up to 50 MB. A job whose references cannot be used fails without a charge.
  • To make shots that follow each other, send them all at once: previous_job_id starts a job from the last frame of another of your jobs, even one still queued or running. It starts when that job has finished, with its last frame added as the last picture (name it in your prompt as the next image), and fails without a charge if that job fails. after_job_id starts a job once another has ended, however it ended. A waiting job holds its price; a key may have 50 waiting.
  • Audio stems (output_mode: "audio-stems") and prompt rewriting (rewrite: true) are Pika's hosted services and are refused with a 422 naming the field.
  • You pay $0.02 a second at 480p and $0.05 at 768p, plus each second of reference video at the same rate; images and audio references are free. See Pricing.
  • Powered by MiniMax H3. Pika H3 Flex is built on MiniMax H3 and used under the MiniMax H3 Community License; its use restrictions apply to every request and output.

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": "qwen3-30b-a3b-instruct-2507", "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.
  • You do not need to retry a provider failure yourself. When a model's first endpoint fails before it answers, the platform tries the next one once, and the request is charged once.
  • You are charged for the tokens the model produced for your request, at most max_tokens, even if you stop reading or disconnect. If you leave a stream after its first words, the platform reads on for up to 25 seconds for the provider's count. A stream that breaks off after its first words is charged the same way, for the tokens the model produced before the break, and ends with an error. The platform stops the model, and charges nothing, only when it sees you leave before any words reach you. A connection that closes before the answer starts is not always reported, so that answer may run and be charged. To limit the cost of an answer you might abandon, set max_tokens.

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"
}
Status Code What it means
400 invalid_request, unsupported_parameter The request body is not valid, or it uses a parameter or value the model does not accept. The message names it.
400 context_length_exceeded The prompt and max_tokens together are longer than the model's context. Shorten the prompt or lower max_tokens.
401 invalid_api_key The key is missing, mistyped or revoked.
402 billing_suspended Billing is not active for the workspace.
402 insufficient_credit Your credit cannot cover the request. Until it finishes, a request holds credit for its prompt and its whole max_tokens (65,536 if you leave it out). Add credit in the console, or set a lower max_tokens.
402 spending_limit_exceeded The request would take the workspace past the monthly spending limit you set.
403 model_binding_mismatch The key is limited to a different model than the one requested.
409 idempotency_conflict The idempotency key was already used with a different body.
429 rate_limited, capacity_limited Too many requests, or the model is at capacity. One workspace may use at most half of a model's capacity at once, so others are never locked out. Wait for the number of seconds in the Retry-After header, then retry.
503 model_unavailable, origin_unavailable The model cannot be reached right now on any of its endpoints. Retry shortly.

Ready to call a model?

Sign up, add credit and create a key. The Quickstart walks you through it.