TLearth One API

OpenAI-compatible. Any OpenAI SDK works by changing the base URL and key.

Base URL: https://<your-domain>/api/public/v1

Endpoints

GET /models
POST /chat/completions — chat + vision, JSON or SSE stream
POST /embeddings
POST /rag — { query, documents[], top_k } → cited answer + ranked sources
No-key guest access from tlearth.com (20 req/min per visitor, no voice)
Extras on /chat/completions: reasoning_effort, response_format (json_schema), tlearth_tools: ["swarm","voice","wallet","escrow","memory","code"]
POST /audio/transcriptions — Voice engine (sovereign only)
POST /audio/speech — Voice engine (sovereign only)

Every response carries x-tlearth-backend: sovereign | fallback and x-request-id. Errors use the OpenAI shape; 429 includes Retry-After.

Quickstart

curl https://<your-domain>/api/public/v1/chat/completions \
  -H "Authorization: Bearer $TLEARTH_MODEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tlearth-one-chat","stream":true,
       "messages":[{"role":"user","content":"Hello"}]}'

// JavaScript (openai SDK)
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://<your-domain>/api/public/v1", apiKey: process.env.TLEARTH_MODEL_KEY });
const r = await client.chat.completions.create({
  model: "tlearth-one-chat",
  messages: [{ role: "user", content: "Hello" }],
});

# Python
from openai import OpenAI
client = OpenAI(base_url="https://<your-domain>/api/public/v1", api_key=os.environ["TLEARTH_MODEL_KEY"])
client.embeddings.create(model="tlearth-one-embed", input="private knowledge")

Integrating into TLearth.com

Create a key in the Console named "TLearth.com production".
In TLearth.com, add secrets TLEARTH_MODEL_URL=https://<your-domain>/api/public/v1 and TLEARTH_MODEL_KEY.
Add a provider in its server gateway:

// src/lib/tlearth-one.server.ts (in TLearth.com)
export async function tlearthOneChat(messages, { stream = true, signal } = {}) {
  const res = await fetch(`${process.env.TLEARTH_MODEL_URL}/chat/completions`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${process.env.TLEARTH_MODEL_KEY}`,
    },
    body: JSON.stringify({ model: "tlearth-one-chat", messages, stream }),
    signal,
  });
  const sovereign = res.headers.get("x-tlearth-backend") === "sovereign";
  return { res, sovereign }; // pipe res.body to the browser; meter usage to the wallet
}

Make TLearth One the default in Studio, Chat and Voice. Show the "Native Sovereign" badge only when sovereign is true.
Read token counts from the final stream chunk's usage to debit the user's wallet.
Replace /fine-tuning with the TLearth One Hub (personas, memory, knowledge bases via /embeddings, tool permissions, evals).

Going sovereign (Modal)

The engine/ folder in this project contains the Modal app. After modal deploy engine/app.py, add these secrets to this project: MODAL_ENGINE_TOKEN, MODAL_CHAT_URL, MODAL_CODE_URL, MODAL_VISION_URL, MODAL_EMBED_URL, MODAL_VOICE_URL. Each model switches to sovereign automatically.