Documentazione dell'API

Per iniziare

I modelli disponibili in questo momento si possono elencare in qualsiasi momento:

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

Se non sai quale modello scegliere, usa auto. Babel Mesh guarda la richiesta: le chiacchiere e le domande semplici vanno a un modello veloce; il codice a un modello per il codice; il ragionamento, i materiali molto lunghi, le chiamate a strumenti o l'output strutturato al modello più potente; e se un modello non ha nodi o ha una coda lunga, se ne usa un altro. La decisione legge solo la richiesta stessa (la lunghezza, se contiene codice, strumenti o uno schema di output strutturato) e non viene conservato nulla. L'intestazione di risposta X-Gateway-Model dice quale modello ha risposto e X-Gateway-Auto perché. auto sceglie solo modelli che il tuo account può usare.

Puoi anche indicarne uno: chat-default (veloce), chat-strong (potente), code-default (codice), embedding-default (embedding), video-default (video). Per le immagini usa il modello z-image-turbo (auto funziona anche per le richieste di immagini). Un alias punta alla scelta migliore del momento; funziona anche il nome proprio del modello.

Chat

L'endpoint è POST /v1/chat/completions; con stream: true la risposta arriva in 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 l'SDK Python di 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="")

Embedding

L'endpoint è POST /v1/embeddings; input è una stringa o un elenco di stringhe.

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

Immagini

L'endpoint è POST /v1/images/generations; l'immagine torna in 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

Il video richiede minuti, quindi è un lavoro asincrono: invialo, interroga lo stato, poi recupera il 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

Ogni account può avere un numero limitato di lavori video in corso. Un video terminato viene conservato per un giorno.

Usarlo da altre app

Poiché l'API è compatibile con OpenAI, funziona con interfacce di chat come Open WebUI, Cherry Studio e Chatbox, e con i plugin di IA degli editor. Aggiungila come provider "compatibile con OpenAI" con due impostazioni:

• Queste app non conoscono l'API dei lavori video (invia, interroga, recupera); per i video chiama direttamente l'API come sopra.
• La cronologia delle conversazioni resta nella tua app; Babel Mesh non la conserva. I contenuti sono trattati secondo la classe di dati dell'account, che per impostazione predefinita è "pubblica" e può essere eseguita sui computer dei contributori: non inserire materiale privato o riservato.
• Se distribuisci un'app del genere per più persone, tutte condividono i crediti e i limiti della stessa chiave.

Errori e limiti

Gli errori hanno il formato di OpenAI: {"error": {"message": "...", "type": "..."}}. Il tuo saldo e i tuoi limiti: GET /v1/account.