API documentation

Getting started

The models available right now can be listed at any time:

curl https://babelmesh.ai/v1/models \
  -H "Authorization: Bearer $BABEL_KEY"

If you do not know which model to pick, use auto. Babel Mesh looks at the request: small talk and simple questions go to a fast model; code goes to a code model; reasoning, very long material, tool calls or structured output go to the strongest model; and if a model has no node or a long queue, another one is used. The decision reads only the request itself (its length, whether it has code, tools or a structured-output schema) and nothing is stored. The response header X-Gateway-Model says which model answered and X-Gateway-Auto why. auto only picks models your account may use.

You can also name one: chat-default (fast), chat-strong (strong), code-default (code), embedding-default (embeddings), video-default (video). For images use the model name z-image-turbo (auto also works for image requests). An alias points to the currently best fit; a model's own name works too.

Chat

The endpoint is POST /v1/chat/completions; stream: true streams the answer.

curl https://babelmesh.ai/v1/chat/completions \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'

With OpenAI's Python SDK:

from openai import OpenAI

client = OpenAI(base_url="https://babelmesh.ai/v1", api_key="sk-fab-...")

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a Python function that checks for palindromes"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Embeddings

The endpoint is POST /v1/embeddings; input is a string or a list of strings.

curl https://babelmesh.ai/v1/embeddings \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "embedding-default", "input": ["a lighthouse at dawn", "a paper boat on a pond"]}'

Images

The endpoint is POST /v1/images/generations; the image comes back as base64 (data[0].b64_json).

curl https://babelmesh.ai/v1/images/generations \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "z-image-turbo", "prompt": "a lighthouse at dawn, watercolor", "n": 1}'

Video

Video takes minutes, so it is an asynchronous job: submit it, poll its status, then fetch the file.

# 1. Submit; the answer holds a job id
curl https://babelmesh.ai/v1/videos \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "video-default", "prompt": "a paper boat on a pond", "seconds": "3"}'

# 2. Poll: queued, in_progress, completed or failed
curl https://babelmesh.ai/v1/videos/VIDEO_ID -H "Authorization: Bearer $BABEL_KEY"

# 3. When completed, fetch the video (mp4)
curl https://babelmesh.ai/v1/videos/VIDEO_ID/content -H "Authorization: Bearer $BABEL_KEY" -o out.mp4

Each account can have a limited number of video jobs in progress. A finished video is kept for one day.

Using it from other apps

Because the API is OpenAI-compatible, it works with chat front ends such as Open WebUI, Cherry Studio and Chatbox, and with AI plugins in editors. Add it as an "OpenAI-compatible" provider with two settings:

• These apps do not know the video job API (submit, poll, fetch); for video call the API directly as above.
• Conversation history stays in your own app; Babel Mesh does not store it. Content is handled by the account's data class, which is "public" by default and may run on contributors' computers: do not enter private or confidential material.
• If you deploy such an app for several people, they all share the one key's credits and limits.

Errors and limits

Errors have OpenAI's shape: {"error": {"message": "...", "type": "..."}}. Your balance and limits: GET /v1/account.