Documentación de la API

Primeros pasos

Los modelos disponibles ahora se pueden consultar en cualquier momento:

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

Si no sabes qué modelo elegir, usa auto. Babel Mesh examina la petición: la charla informal y las preguntas sencillas van a un modelo rápido; el código, a un modelo de código; el razonamiento, los materiales muy largos, las llamadas a herramientas o la salida estructurada, al modelo más potente; y si un modelo no tiene nodo o tiene mucha cola, se usa otro. La decisión solo lee la propia petición (su longitud, si tiene código, herramientas o un esquema de salida estructurada) y no se guarda nada. La cabecera de respuesta X-Gateway-Model indica qué modelo respondió y X-Gateway-Auto el motivo. auto solo elige modelos que tu cuenta puede usar.

También puedes indicar uno: chat-default (rápido), chat-strong (potente), embedding-default (embeddings), video-default (vídeo). Para imágenes usa el modelo z-image-turbo (auto también funciona en peticiones de imagen). Un alias apunta a lo que mejor encaja ahora; el nombre propio del modelo también sirve.

Chat

El endpoint es POST /v1/chat/completions; con stream: true la respuesta llega en 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"}]
  }'

Con el SDK de Python de 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

El endpoint es POST /v1/embeddings; input es una cadena o una lista de cadenas.

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

Imágenes

El endpoint es POST /v1/images/generations; la imagen vuelve en 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

El vídeo tarda minutos, así que es un trabajo asíncrono: envíalo, consulta su estado y descarga el archivo.

# 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 cuenta puede tener un número limitado de trabajos de vídeo en curso. Un vídeo terminado se conserva durante un día.

Usarlo desde otras aplicaciones

Como la API es compatible con OpenAI, funciona con interfaces de chat como Open WebUI, Cherry Studio y Chatbox, y con los complementos de IA de los editores. Añádela como proveedor "compatible con OpenAI" con dos ajustes:

• Estas aplicaciones no conocen la API de trabajos de vídeo (enviar, consultar, descargar); para vídeo llama a la API directamente como arriba.
• El historial de conversaciones se queda en tu propia aplicación; Babel Mesh no lo guarda. El contenido se trata según la clase de datos de la cuenta, que por defecto es "pública" y puede ejecutarse en los equipos de los colaboradores: no introduzcas material privado ni confidencial.
• Si despliegas una aplicación así para varias personas, todas comparten los créditos y los límites de esa clave.

La interfaz local del cliente

El cliente de Babel Mesh también puede responder en tu propio equipo, para que los programas de allí usen la red como usarían un modelo local. Está desactivado hasta que actives "API local" en la página de cuenta del cliente. Solo escucha en este equipo (puerto predeterminado 18650; el cliente muestra la dirección exacta), y los programas usan un token que muestra el cliente, no la clave de tu cuenta.

• Las herramientas que esperan Ollama en su puerto habitual, el 11434, también se atienden allí, pero solo cuando Ollama no está instalado ni en ejecución en ese equipo, así que nunca se disputan el puerto.
• Funciona con Claude Code, Open WebUI, Continue, Cursor, Cherry Studio, LobeChat y los SDK de OpenAI y Ollama.
• Las peticiones siguen hacia la red como tu cuenta, así que se gastan créditos como siempre y se aplica la misma clase de datos.

Desde otro lugar, con la misma cuenta

Se puede llegar a la dirección pública https://babelmesh.ai/v1 desde cualquier lugar con la clave de tu cuenta, así que otro equipo, un servidor o una aplicación del móvil pueden conectarse directamente. Hoy esa dirección habla la API compatible con OpenAI. Para herramientas al estilo Ollama y Anthropic en otro equipo, instala allí el cliente, inicia sesión con la misma cuenta y usa su interfaz local como se indica arriba. El cliente no abre ningún puerto de entrada, así que su interfaz local no es accesible desde otras máquinas.

Previsto, sin fecha: endpoints al estilo Anthropic y Ollama también en la dirección pública.

Errores y límites

Los errores tienen el formato de OpenAI: {"error": {"message": "...", "type": "..."}}. Tu saldo y tus límites: GET /v1/account.