Connecting via the Claude SDK

Before you begin

How it works

Mealissa exposes your nodes through the Anthropic Messages API format, so the official Claude SDKs work with two changed settings:

• Base URL — https://mealissa.com/cloud/g/<group> to query any online node in a group, or https://mealissa.com/cloud/n/<node_id> to pin a specific node. The SDK appends /v1/messages itself.
• API key — your Mealissa license key.
• Model — the Ollama tag your node serves (e.g. qwen2.5:4b), not a claude-* id.

---

Python quick start

pip install anthropic

import anthropic

client = anthropic.Anthropic(
    base_url="https://mealissa.com/cloud/g/<your-group>",
    api_key="<your-license-key>",
    timeout=600.0,
)

response = client.messages.create(
    model="qwen2.5:4b",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from the Claude SDK!"}],
)
print(response.content[0].text)

Prefer configuration by environment? The SDK picks these up automatically:

export ANTHROPIC_BASE_URL=https://mealissa.com/cloud/g/<your-group>
export ANTHROPIC_API_KEY=<your-license-key>

TypeScript quick start

npm install @anthropic-ai/sdk

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://mealissa.com/cloud/g/<your-group>",
  apiKey: "<your-license-key>",
  timeout: 600000,
});

const response = await client.messages.create({
  model: "qwen2.5:4b",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello from the Claude SDK!" }],
});
console.log(response.content[0].text);

---

System prompts and multi-turn

Conversation history and the system field work as usual — Mealissa flattens them into a single prompt for your local model:

response = client.messages.create(
    model="qwen2.5:4b",
    max_tokens=1024,
    system="You are a concise assistant.",
    messages=[
        {"role": "user", "content": "What is the capital of France?"},
        {"role": "assistant", "content": "Paris."},
        {"role": "user", "content": "And its population?"},
    ],
)

---

What's supported

Mealissa forwards text prompts to your local Ollama models — it speaks the Messages API wire format, but local models don't have every Claude capability. Be explicit about what your code can rely on:

• Works — messages.create() with text content, system prompts, multi-turn history, and a per-request timeout field (default 600 s).
• Streaming — messages.stream() is not supported on the Anthropic-format endpoint. If you need token streaming, use the OpenAI-compatible endpoint, which supports SSE via stream: true.
• Not supported — tool use, extended thinking, token counting (count_tokens), and image or document content blocks.
• Usage numbers — response.usage currently reports 0 input/output tokens; request latency and status are tracked in the Usage dashboard instead.
• max_tokens — accepted for compatibility, but the reply length is governed by your local model's own settings.

---

Long requests and timeouts

Local models on modest hardware can take a while. The connection is kept alive while your node computes; if the model doesn't answer within the request's timeout (default 600 s), the API returns 504. For slow models, raise the SDK client timeout and, if needed, send a larger timeout value in the request body.

Common errors are listed in Troubleshooting — including 404 node not found or offline and 401 for an invalid key.

---

Next steps

• Prefer OpenAI format? — the same nodes answer at /v1/chat/completions. See the OpenAI-compatible endpoint guide.
• See your traffic — requests appear in the Usage dashboard.
• Overview of SDK compatibility — see Compatible SDKs.