Documentação da API

Primeiros passos

Os modelos disponíveis agora podem ser listados a qualquer momento:

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

Se você não sabe qual modelo escolher, use auto. O Babel Mesh olha a requisição: conversa casual e perguntas simples vão para um modelo rápido; código vai para um modelo de código; raciocínio, material muito longo, chamadas de ferramentas ou saída estruturada vão para o modelo mais forte; e se um modelo não tem nó ou tem fila longa, outro é usado. A decisão lê apenas a própria requisição (o tamanho, se há código, ferramentas ou um esquema de saída estruturada) e nada é guardado. O cabeçalho de resposta X-Gateway-Model informa qual modelo respondeu e X-Gateway-Auto o motivo. O auto só escolhe modelos que sua conta pode usar.

Você também pode indicar um: chat-default (rápido), chat-strong (forte), code-default (código), embedding-default (embeddings), video-default (vídeo). Para imagens, use o modelo z-image-turbo (o auto também funciona em requisições de imagem). Um alias aponta para a melhor opção do momento; o nome próprio do modelo também funciona.

Chat

O endpoint é POST /v1/chat/completions; com stream: true a resposta vem em streaming.

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"}]
  }'

Com o SDK Python da OpenAI:

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

O endpoint é POST /v1/embeddings; input é uma string ou uma lista de 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"]}'

Imagens

O endpoint é POST /v1/images/generations; a imagem volta em 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}'

Vídeo

Vídeo leva minutos, então é uma tarefa assíncrona: envie, consulte o status e depois busque o arquivo.

# 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

Cada conta pode ter um número limitado de tarefas de vídeo em andamento. Um vídeo pronto fica guardado por um dia.

Usando em outros aplicativos

Como a API é compatível com a OpenAI, ela funciona com interfaces de chat como Open WebUI, Cherry Studio e Chatbox, e com plugins de IA em editores. Adicione-a como provedor "compatível com a OpenAI" com duas configurações:

• Esses aplicativos não conhecem a API de tarefas de vídeo (enviar, consultar, buscar); para vídeo, chame a API diretamente como acima.
• O histórico de conversas fica no seu próprio aplicativo; o Babel Mesh não o guarda. O conteúdo é tratado conforme a classe de dados da conta, que por padrão é "pública" e pode rodar em computadores de colaboradores: não digite material privado ou confidencial.
• Se você implantar um aplicativo assim para várias pessoas, todas compartilham os créditos e limites da mesma chave.

Erros e limites

Os erros têm o formato da OpenAI: {"error": {"message": "...", "type": "..."}}. Seu saldo e seus limites: GET /v1/account.