API 문서

시작하기

지금 이용 가능한 모델은 언제든 조회할 수 있습니다:

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

어떤 모델을 골라야 할지 모르겠다면 auto를 쓰세요. Babel Mesh는 요청을 보고 나눕니다. 잡담과 간단한 질문은 빠른 모델로, 코드는 코드 모델로, 추론·아주 긴 자료·도구 호출·구조화된 출력은 가장 강력한 모델로 보냅니다. 어떤 모델에 노드가 없거나 대기열이 길면 다른 모델을 씁니다. 판단은 요청 자체(길이, 코드·도구·구조화 출력 스키마 포함 여부)만 읽으며 아무것도 저장하지 않습니다. 응답 헤더 X-Gateway-Model은 어느 모델이 답했는지, X-Gateway-Auto는 그 이유를 알려 줍니다. auto는 내 계정이 쓸 수 있는 모델만 고릅니다.

직접 지정할 수도 있습니다: chat-default(빠름), chat-strong(강력), embedding-default(임베딩), video-default(동영상). 이미지는 모델 이름 z-image-turbo를 쓰세요(이미지 요청에도 auto를 쓸 수 있습니다). 별칭은 현재 가장 알맞은 모델을 가리키며, 모델 자체의 이름도 쓸 수 있습니다.

채팅

엔드포인트는 POST /v1/chat/completions이며, stream: true로 답을 스트리밍합니다.

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

OpenAI의 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="")

임베딩

엔드포인트는 POST /v1/embeddings이며, input은 문자열 또는 문자열 목록입니다.

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

이미지

엔드포인트는 POST /v1/images/generations이며, 이미지는 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}'

동영상

동영상은 몇 분이 걸리므로 비동기 작업입니다. 제출하고, 상태를 조회하고, 파일을 가져옵니다.

# 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

계정마다 동시에 진행할 수 있는 동영상 작업 수에 한도가 있습니다. 완성된 동영상은 하루 동안 보관됩니다.

다른 앱에서 사용하기

이 API는 OpenAI 호환이므로 Open WebUI, Cherry Studio, Chatbox 같은 채팅 프런트엔드와 편집기의 AI 플러그인에서 쓸 수 있습니다. "OpenAI 호환" 공급자로 다음 두 가지를 설정해 추가하세요.

• 이 앱들은 동영상 작업 API(제출, 조회, 가져오기)를 모릅니다. 동영상은 위에서처럼 API를 직접 호출하세요.
• 대화 기록은 내 앱에 남으며 Babel Mesh는 저장하지 않습니다. 콘텐츠는 계정의 데이터 등급에 따라 처리되는데, 기본값은 "공개"이며 기여자의 컴퓨터에서 실행될 수 있으므로 개인 정보나 기밀 자료는 입력하지 마세요.
• 이런 앱을 여러 사람에게 배포하면 모두가 하나의 키의 크레딧과 한도를 함께 씁니다.

클라이언트의 로컬 인터페이스

Babel Mesh 클라이언트는 내 컴퓨터에서도 응답할 수 있어서, 그 컴퓨터의 프로그램이 로컬 모델을 쓰듯 네트워크를 쓸 수 있습니다. 클라이언트의 계정 페이지에서 "로컬 API"를 켜기 전에는 꺼져 있습니다. 이 컴퓨터에서만 수신하며(기본 포트 18650, 정확한 주소는 클라이언트에 표시됨), 프로그램은 계정 키가 아니라 클라이언트가 보여 주는 토큰을 씁니다.

• 기본 포트 11434에서 Ollama를 기대하는 도구도 그곳에서 응답받지만, 그 컴퓨터에 Ollama 자체가 설치되어 있지도 실행 중이지도 않을 때만 그렇습니다. 그래서 둘이 포트를 두고 다투는 일은 없습니다.
• Claude Code, Open WebUI, Continue, Cursor, Cherry Studio, LobeChat, 그리고 OpenAI와 Ollama의 SDK와 함께 쓸 수 있습니다.
• 요청은 내 계정으로 네트워크에 전달되므로 크레딧은 평소처럼 사용되고 같은 데이터 등급이 적용됩니다.

다른 곳에서, 같은 계정으로

공개 주소 https://babelmesh.ai/v1은 계정 키만 있으면 어디서든 접속할 수 있어서, 다른 컴퓨터, 서버, 휴대폰 앱이 바로 연결할 수 있습니다. 현재 이 주소는 OpenAI 호환 API를 지원합니다. 다른 컴퓨터에서 Ollama 방식이나 Anthropic 방식 도구를 쓰려면, 그 컴퓨터에 클라이언트를 설치하고 같은 계정으로 로그인한 다음 위에서 설명한 로컬 인터페이스를 쓰세요. 클라이언트는 들어오는 포트를 열지 않으므로, 클라이언트의 로컬 인터페이스는 다른 기기에서 접속할 수 없습니다.

계획 중, 날짜 미정: 공개 주소에서도 Anthropic 방식과 Ollama 방식의 엔드포인트를 제공할 예정입니다.

오류와 한도

오류는 OpenAI와 같은 형식입니다: {"error": {"message": "...", "type": "..."}}. 잔액과 한도는 GET /v1/account로 확인할 수 있습니다.