AI (totalum-sdk/ai)

const { text } = await totalum.ai.chat({ model: 'fast', messages: [{ role: 'user', content: 'Say hi' }] });

totalumAi(options?: TotalumAiOptions): TotalumAi

import { totalumAi } from 'totalum-sdk/ai';

const ai = totalumAi();
const { text } = await ai.chat({ messages: [{ role: 'user', content: 'Hello' }] });

ai.chat(req: { model?, messages, tools?, toolChoice?, parallelToolCalls?, responseFormat?, temperature?, maxTokens?, reasoning?, serverTools?, maxToolCalls?, cache?, zdr?, fastMode?, user? }): Promise<ChatResult>

const reply = await totalum.ai.chat({
  model: 'fast',
  messages: [
    { role: 'system', content: 'Answer in one word.' },
    { role: 'user', content: 'What is the capital of France?' },
  ],
});

{
  "id": "gen-1791740364-UbQ0IKv75XZajyP5We6y",
  "model": "openai/gpt-6-luna",
  "text": "Paris",
  "toolCalls": [],
  "finishReason": "stop",
  "usage": { "credits": 0.0007, "inputTokens": 0, "outputTokens": 0 },
  "raw": { "id": "gen-1791740364-UbQ0IKv75XZajyP5We6y", "object": "chat.completion", "choices": [ … ], … }
}

// tool calling: the model asks for getWeather, you run it and send the answer back
const first = await totalum.ai.chat({
  messages: [{ role: 'user', content: 'Weather in Madrid?' }],
  tools: [{ type: 'function', function: { name: 'getWeather', parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } } }],
});

{ "text": "", "toolCalls": [{ "id": "call_8f2k", "type": "function", "function": { "name": "getWeather", "arguments": "{\"city\":\"Madrid\"}" } }], "finishReason": "tool_calls", … }

ai.generateObject(req: { schema, prompt?, messages?, model?, healing? }): Promise<{ object, usage }>

const { object } = await totalum.ai.generateObject({
  model: 'fast',
  prompt: 'Ana is 31 and lives in Madrid.',
  schema: {
    type: 'object',
    properties: { name: { type: 'string' }, age: { type: 'number' }, city: { type: 'string' } },
    required: ['name', 'age', 'city'],
    additionalProperties: false,
  },
});

{ "object": { "name": "Ana", "age": 31, "city": "Madrid" }, "usage": { "credits": 0.0014 } }

ai.classify(req: { input, options, model?, instructions? }): Promise<{ label }>

const { label } = await totalum.ai.classify({
  input: 'My card was charged twice',
  options: ['billing', 'bug', 'other'],
  model: 'fast',
});

{ "label": "billing" }

ai.embed(req: AiEmbedInput): Promise<AiEmbedOutput>

const { embeddings } = await totalum.ai.embed({ input: ['red shoes', 'blue sandals'] });

{ "embeddings": [[0.0138, -0.0121, 0.0125, …], [0.0042, -0.0337, 0.0198, …]], "usage": { "credits": 0.0001 } }

ai.image.generate(req: AiImageInput): Promise<AiImageOutput>

const { images } = await totalum.ai.image.generate({
  prompt: 'A watercolor fox reading a book, warm light',
  aspectRatio: '16:9',
});

{
  "images": [
    { "key": "p/acme-crm/01M4P1J2K3L4M5N6P7Q8R9S0TV.png", "url": "https://files.totalum-project.com/p/acme-crm/01M4P1J2K3L4M5N6P7Q8R9S0TV.png", "mediaType": "image/png", "width": 1344, "height": 768 }
  ],
  "usage": { "credits": 0.2741 },
  "fileName": "01M4P1J2K3L4M5N6P7Q8R9S0TV.png",
  "imageUrl": "https://files.totalum-project.com/p/acme-crm/01M4P1J2K3L4M5N6P7Q8R9S0TV.png"
}

ai.image.edit(req: AiImageEditInput): Promise<AiImageOutput>

const { images } = await totalum.ai.image.edit({
  prompt: 'Put this sneaker on a white marble pedestal, studio light',
  images: [product.photo.url],
});

{
  "images": [{ "key": "p/acme-crm/01M4P1K3L4M5N6P7Q8R9S0T1UW.png", "url": "https://files.totalum-project.com/p/acme-crm/01M4P1K3L4M5N6P7Q8R9S0T1UW.png", "mediaType": "image/png" }],
  "usage": { "credits": 0.3012 },
  "fileName": "01M4P1K3L4M5N6P7Q8R9S0T1UW.png",
  "imageUrl": "https://files.totalum-project.com/p/acme-crm/01M4P1K3L4M5N6P7Q8R9S0T1UW.png"
}

ai.video.generate(req: AiVideoInput): Promise<AiVideoCreated>

const job = await totalum.ai.video.generate({
  prompt: 'A paper boat sailing down a rainy street, cinematic',
  durationSec: 5,
  aspectRatio: '16:9',
});
// save job.jobId on the row, then read ai.video.get(jobId) later

{ "jobId": "vid_8m2k4n6p8q0r", "status": "queued", "estimatedCredits": 21.5 }

ai.video.get(jobId: string): Promise<AiVideoJob>

const job = await totalum.ai.video.get('vid_8m2k4n6p8q0r');

{
  "jobId": "vid_8m2k4n6p8q0r",
  "status": "completed",
  "video": { "key": "p/acme-crm/01M4P1M5N6P7Q8R9S0T1U2V3WX.mp4", "url": "https://files.totalum-project.com/p/acme-crm/01M4P1M5N6P7Q8R9S0T1U2V3WX.mp4" },
  "usage": { "credits": 19.8 }
}

ai.video.wait(jobId: string, opts?: { intervalMs?, timeoutMs? }): Promise<AiVideoJob>

// scripts/make-intro-video.ts, run with: npx tsx scripts/make-intro-video.ts
const { jobId } = await totalum.ai.video.generate({ prompt: 'Logo reveal on black', durationSec: 5 });
const job = await totalum.ai.video.wait(jobId);
console.log(job.status, job.video?.url);

completed https://files.totalum-project.com/p/acme-crm/01M4P1M5N6P7Q8R9S0T1U2V3WX.mp4

ai.vision.describe(req: AiVisionDescribeInput): Promise<AiTextOutput>

const { text } = await totalum.ai.vision.describe({
  image: 'p/acme-crm/01M4P1J2K3L4M5N6P7Q8R9S0TV.png',
  prompt: 'Write alt text for this image in one sentence.',
});

{ "text": "A watercolor fox sits under a lamp reading an open book.", "usage": { "credits": 0.0019 } }

ai.speech.speak(input: { text, voice?, language?, model?, format?, speed?, store }): Promise<StoredMedia>
ai.speech.speak(input: SpeakInput): Promise<StoredMedia | SpeechAudio>

ai.speech.transcribe(input: TranscribeInput): Promise<TranscribeOutput>

ai.models.list(): Promise<AiModelsOutput>

const { presets, models } = await totalum.ai.models.list();

{
  "presets": {
    "fast": "openai/gpt-6-luna",
    "smart": "openai/gpt-6.1-sol",
    "reasoning": "anthropic/claude-opus-5.5",
    "vision": "openai/gpt-6-luna",
    "image": "microsoft/mai-image-2.6-flash",
    "image-edit": "microsoft/mai-image-2.6-flash",
    "video": "alibaba/wan-3.0",
    "tts": "microsoft/mai-voice-2.1-flash",
    "stt": "openai/whisper-large-v3-turbo",
    "embed": "openai/text-embedding-3-small",
    "embed-image": "google/gemini-embedding-2"
  },
  "models": [
    { "slug": "anthropic/claude-haiku-5.5", "name": "Anthropic: Claude Haiku 5.5", "inputModalities": ["text", "image", "file"], "pricing": {}, "contextLength": 1000000 },
    …
  ]
}

ai.gatewayConfig(): { baseURL, apiKey }

import OpenAI from 'openai';

const openai = new OpenAI(totalum.ai.gatewayConfig());
const r = await openai.chat.completions.create({ model: 'fast', messages: [{ role: 'user', content: 'Hi' }] });

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const gateway = createOpenAI(totalum.ai.gatewayConfig());
const { text } = await generateText({ model: gateway('smart'), prompt: 'Write a haiku about Mondays' });

{ "baseURL": "https://ai.totalum.app/api/v1", "apiKey": "tlm_pk_…" }

stream.text(): AsyncIterable<string>

const stream = await totalum.ai.chat.stream({ model: 'fast', messages: [{ role: 'user', content: 'Count 1 to 3.' }] });
for await (const piece of stream.text()) process.stdout.write(piece);

"1" ", " "2" ", " "3" "."

stream.result(): Promise<ChatResult>

const stream = await totalum.ai.chat.stream({ model: 'fast', messages: [{ role: 'user', content: 'Count 1 to 3.' }] });
const result = await stream.result();

{
  "id": "gen-1791740371-wfMT8WhpKYrAEa1s9XKT",
  "model": "openai/gpt-6-luna",
  "text": "1, 2, 3.",
  "toolCalls": [],
  "finishReason": "stop",
  "usage": { "credits": 0.0005, "inputTokens": 0, "outputTokens": 0 },
  "raw": { "id": "gen-1791740371-wfMT8WhpKYrAEa1s9XKT", "model": "openai/gpt-6-luna", "text": "1, 2, 3.", "choices": [{ "message": { "content": "1, 2, 3." }, "finish_reason": "stop" }] }
}