Docs

Quickstart

1. Request access: fill in the business access form. Access is free for approved businesses.
2. Once approved, create a key on the keys page. It's shown once, so copy it.
3. Send a request with the key in the Authorization header, and read the result: the audio file, or a job you poll until it's done.

export MASHBOX_API_KEY="your key"
curl https://inference.mashbox.gg/v1/models -H "Authorization: Bearer $MASHBOX_API_KEY"

Calling the API

• HTTP with JSON bodies, from any language. Base URL: https://inference.mashbox.gg/v1
• OpenAI SDK. Text to speech takes the OpenAI speech request. Set the base URL to https://inference.mashbox.gg/v1 and use your MASHBOX key. See OpenAI compatibility.

Authentication

Send Authorization: Bearer $MASHBOX_API_KEY on every request. Create and manage keys on the keys page; a new key is shown once. Keys belong on servers: a request that carries a browser Origin header is refused with origin_not_allowed.

GET /v1/key describes the key you call it with.

MASHBOX Creature

Pipeline Experimental For approved accounts

Experimental: output quality is still improving; results may need cleanup.

One text prompt in; a textured, rigged and animated 3D creature out, as a GLB file. POST /v1/creatures with model mbx-creature answers 202 at once with a job: its id and status. The job also gives position, its place in the queue, eta_s, the estimated seconds until it is done, progress, how far along it is and stage, the step it is on. Poll the job until it is completed, then download the files. A creature takes minutes, not seconds. You can also try it in the playground.

Each request runs these steps in order:

1. A concept image from your prompt, made with Z-Image Turbo.
2. A 3D mesh built from that image.
3. Texture painted onto the mesh.
4. A skeleton and skin weights fitted to the mesh.
5. Motion clips for that skeleton, from our own motion model.
6. Everything packed into one GLB file for your game.

Request fields

curl https://inference.mashbox.gg/v1/creatures \
  -H "Authorization: Bearer $MASHBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "mbx-creature", "prompt": "a six-legged desert lizard with a spiked tail"}'

# then, every 2 seconds until status is completed or failed:
curl https://inference.mashbox.gg/v1/jobs/$JOB_ID -H "Authorization: Bearer $MASHBOX_API_KEY"

import os, time, requests

H = {"Authorization": "Bearer " + os.environ["MASHBOX_API_KEY"]}
job = requests.post("https://inference.mashbox.gg/v1/creatures", headers=H, json={"model": "mbx-creature", "prompt": "a six-legged desert lizard with a spiked tail"}, timeout=60).json()
while job["status"] not in ("completed", "failed", "cancelled"):
    time.sleep(2)
    job = requests.get("https://inference.mashbox.gg/v1/jobs/" + job["id"], headers=H, timeout=60).json()
print(job)

Maya1 text to speech

Model For approved accounts

Text in, speech out, in a voice you describe in plain words. POST /v1/audio/speech with model maya1 answers with the audio itself. Built on Maya1 by Maya Research.

Request fields

curl https://inference.mashbox.gg/v1/audio/speech \
  -H "Authorization: Bearer $MASHBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "maya1", "input": "Hold the gate! They'\''re coming over the ridge.", "voice": {"description": "A gruff old blacksmith with a deep, slow voice."}, "response_format": "wav"}' \
  --output speech.wav

One request makes up to 120 seconds of audio. The male and female presets are neutral: emotion comes from the tags below and from emotion and intensity words in a voice description, for example an excited young woman, high intensity.

Emotion tags

Put a tag where the sound or change of delivery should happen. Results depend on the text, the voice description and where the tag sits, so try a few placements. Only these 20 tags work.

Real-time voice conversation, speech in and speech out: coming soon.

Jobs

Creatures run as jobs. The request answers at once with the job's id and status. Poll GET /v1/jobs/{id} about every 2 seconds. Statuses: queued, in_progress, moderating, completed, failed, cancelled. Cancel with POST /v1/jobs/{id}/cancel.

• Idempotency-Key: send the same key to retry a request safely.
• Outputs: signed URLs that last 10 minutes. Fresh ones come from GET /v1/jobs/{id}/files. Outputs are kept 7 days.

Errors

Errors use the OpenAI error shape, with extra fields that say what to do next: request_id, limit_source, remedy, resets_at and docs, a link to the row below. Busy answers are 429 with Retry-After; wait that many seconds and retry. A model_loading answer also carries error.loading with state and eta_s. insufficient_quota is a 429 without Retry-After: retrying does not help.

Limits

Each account and each key has a request rate and a number of runs in flight. Every response carries X-RateLimit-Limit-Requests, X-RateLimit-Remaining-Requests and X-RateLimit-Reset-Requests. GET /v1/limits returns your current limits as JSON. Over a limit you get 429 with Retry-After.

Evaluation quota

Each approved company gets 10 creatures and 30 minutes of audio per 30 days, free. Need more? Write to [email protected]. When it is used up, requests answer 429.

When a demo is paused

A paused demo answers 429 model_unavailable with Retry-After. GET /v1/status shows which demos are live.

OpenAI compatibility

Text to speech works with the official OpenAI SDKs: point the client at https://inference.mashbox.gg/v1 and pass your MASHBOX key. Errors use the OpenAI error shape. Creatures have no OpenAI equivalent; call them over HTTP.

from openai import OpenAI
import os

client = OpenAI(base_url="https://inference.mashbox.gg/v1", api_key=os.environ["MASHBOX_API_KEY"])
with client.audio.speech.with_streaming_response.create(
    model="maya1",
    input="Hold the gate! They're coming over the ridge.",
    voice={"description": "A gruff old blacksmith with a deep, slow voice."},
    response_format="wav",
) as r:
    r.stream_to_file("speech.wav")

Models

GET /v1/models lists what the API serves right now. It's public: no key needed.

curl https://inference.mashbox.gg/v1/models

Status

GET /v1/status gives each model's live state. Public, no key needed.

curl https://inference.mashbox.gg/v1/status

Packs

The other 11 catalog models are available as Packs, with example outputs for each on the Packs page. Write to [email protected].

Measured results are on the research page.