ยง 04 ยท Developer API & SDK

Install. Configure. Ship.

One import replaces your OpenAI client. The SDK negotiates with the mesh on the first request and routes automatically from there.

4.1

Install

bash
# Browser / Node
npm install @meshinfer.ai/sdk

# React bindings
npm install @meshinfer.ai/react

# Python
pip install meshinfer.ai

# Desktop (auto-updates after install)
curl -fsSL https://meshinfer.ai/install.sh | sh
4.2

Quickstart

javascript
import { MeshInfer } from '@meshinfer.ai/sdk';

const mesh = new MeshInfer({ apiKey: 'msk_live_...' });

const res = await mesh.chat({
  model: 'local-small',
  messages: [{ role: 'user', content: 'Hello' }],
  latency_preference: 'low',
  cost_preference:    'cheap',
});

console.log(res.choices[0].message.content);
console.log('routed via:', res.route);   // 'local' | 'mesh' | 'cloud'
console.log('cost saved:', res.savings_usd);
4.3

REST reference

Endpoints

MethodPathPurpose
POST/v1/ai/chatChat completion (streaming & non-streaming)
POST/v1/ai/embedGenerate embeddings (mesh-routed)
POST/v1/ai/classifyZero-shot classification
GET/v1/modelsList models + availability per route
GET/v1/usageMetering dump for the current billing cycle
POST/v1/policiesCreate routing/privacy policy
GET/v1/nodes/meInspect this user-agent's mesh contribution

Request parameters โ€” /v1/ai/chat

FieldTypeDefaultNotes
modelstringlocal-smallSee ยง4.4 for catalog
messagesMessage[]โ€”OpenAI format
streambooleanfalseSSE when true
latency_preferenceenumbalancedlow ยท balanced ยท quality
cost_preferenceenumbalancedcheap ยท balanced ยท premium
privacyenumdefaultdefault ยท local-only ยท mesh-ok ยท no-cloud
max_tokensint1024
temperaturenumber0.7
policy_idstringnullReference a pre-registered policy
4.4

Model catalog

AliasReal modelLocal?Mesh?Cloud fallback
local-smallLlama-3.2-1B-Instructโœ“โœ“gpt-5-mini
local-midPhi-3.5-mini (3.8B)โœ“โœ“gpt-5-mini
local-7bQwen-2.5-7B-Instructdesktop onlyโœ“gpt-5-mini
embed-smallBGE-M3โœ“โœ“โ€” (mesh-only)
cloud-proautoโœ—โœ—gpt-5-mini
4.5

Error codes

CodeHTTPMeaningRecommended action
mesh_no_capacity503No local/peer node could accept the task in budgetSDK auto-retries to cloud
policy_violation403Request violates privacy policy (e.g., cloud forbidden)Relax policy or use local-only model
model_unavailable404Requested model not distributed yetCall /v1/models to discover
quota_exceeded429API-key or user rate limitRespect Retry-After
verification_fail422Output failed verification sampleAuto-retried once transparently
node_quarantined451Caller's own node flagged โ€” contact supportSupport ticket
auth_invalid401Bad / revoked API keyRotate key
4.6

SDK init options

typescript
new MeshInfer({
  apiKey: string,
  mode?: 'auto' | 'local-only' | 'cloud-only' | 'mesh',   // default 'auto'
  maxLocalRamMb?: number,          // default 40% of ram_free
  allowMeshParticipation?: boolean,// default true โ€” user contributes back
  consent?: 'explicit' | 'implicit',// default 'explicit' (GDPR)
  telemetry?: boolean,             // default true, anonymous perf only
  endpoint?: string,               // override (for on-prem coordinator)
});
OpenAI drop-in
The SDK exposes an openai-compatible surface. Swap new OpenAI() for new MeshInfer.AI() and ship.