- Developers
- Token Factory docs
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 QuickstartKeys 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
}'
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": "qwen3-30b-a3b-instruct-2507",
"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: "qwen3-30b-a3b-instruct-2507",
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.
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_audiotofalsefor 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.
-
resolutionis480p,768p(the default),1080p,2kor4k(the last three are made at 768p and upscaled once);aspect_ratiois 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, andautogives 16:9;seedmakes 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_idstarts 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_idstarts 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
202with 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, setmax_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.