The @atai-group/sdk and the Atai Runtime API

Your application (@atai-group/sdk)
        │  Authorization: Bearer atai_<environment>_<secret>
        ▼
Atai Runtime API  (https://atai.ink/api/runtime/v1)
   authenticate → authorize → validate → route
        ▼
Atai providers & infrastructure  (never visible to your app)

npm install @atai-group/sdk

pnpm add @atai-group/sdk

yarn add @atai-group/sdk

atai_<environment>_<secret>

atai_production_a81fK2x9dQ7vN4mZpLw3sE6rT1yU8iO0   ← production key
atai_development_b2cD4eF6gH8jK1lM3nP5qR7s9tU2vW4x  ← development key

["ai.text", "email", "payments"]   ← only these three capabilities
[]                                 ← all entitled capabilities

import { Atai } from "@atai-group/sdk"

const atai = new Atai({
  apiKey: process.env.ATAI_API_KEY!,   // atai_<environment>_<secret>
  // baseUrl is optional — defaults to Atai's production runtime origin.
})

const result = await atai.ai.chat({
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Write a haiku about databases." },
  ],
  temperature: 0.7,
  max_tokens: 200,
})

console.log(result.content)             // the assistant's reply
console.log(result.model)               // the model Atai actually used
console.log(result.usage?.totalTokens)  // token usage for this call

const health = await atai.health.check()

console.log(health.status)               // "operational"
console.log(health.identity.projectId)   // your project, from the key record
console.log(health.identity.environment) // "development" | "production"

const dev = new Atai({ apiKey: process.env.ATAI_DEV_KEY! })
const prod = new Atai({ apiKey: process.env.ATAI_PROD_KEY! })

const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

try {
  await atai.ai.chat({ messages: [{ role: "user", content: "Long task?" }] }, { signal: controller.signal })
} catch (e) {
  // e.code === "atai_aborted" when cancelled by the caller
}

const result = await atai.ai.chat({
  model: "openai/gpt-5.2",       // optional — Atai's default model otherwise
  messages: [
    { role: "system", content: "You are concise." },
    { role: "user", content: "Summarize this order." },
  ],
  max_tokens: 300,               // 1–1,000,000
  temperature: 0.4,              // 0–2
  stop: ["###"],                 // string or up to 4 strings
  seed: 42,
})

// result: { id, model, content, finishReason, usage? }

await atai.email.send({
  to: ["customer@example.com"],
  subject: "Your receipt",
  text: "Thanks for your purchase!",
  html: "<p>Thanks for your purchase!</p>",
  replyTo: "support@yourapp.com",
})
// → { id }

await atai.sms.send({ to: "+15551234567", body: "Your code is 8291" })
await atai.whatsapp.send({ to: "+15551234567", body: "Order confirmed 🎉" })
// → { messageId, status, segments? }

const { records, total } = await atai.db.query({
  tableName: "orders",
  filter: { status: "paid" },
  sortBy: "createdAt",
  sortDirection: "desc",
  limit: 20,
  skip: 0,
})

const created = await atai.db.create({ tableName: "orders", data: { item: "Latte", qty: 2 } })
const updated = await atai.db.edit({ tableName: "orders", recordId: created.id!, data: { status: "paid" } })
await atai.db.delete({ tableName: "orders", recordId: created.id! })

const checkout = await atai.payments.createCheckout({
  items: [{ name: "Pro plan", quantity: 1, price: 19.99 }],
  customerEmail: "customer@example.com",
  successUrl: "https://yourapp.com/success",
  cancelUrl: "https://yourapp.com/pricing",
  idempotencyKey: "order-8291",   // deduplicates retries
  currency: "USD",
})
// → { checkoutId, checkoutUrl, status } — redirect the customer to checkoutUrl

// Image generation (text-to-image, or image-to-image via input_references)
const image = await atai.image.generateImage({
  prompt: "A red panda astronaut floating in space",
  model: "google/gemini-2.5-flash-image",   // OpenRouter model id
  aspect_ratio: "16:9",
})
// → { images: [{ b64, mediaType }] } — base64-encoded image bytes

// Video generation (async job — submit, then poll with { jobId })
const job = await atai.video.generateVideo({
  prompt: "A timelapse of a city skyline at dusk",
  model: "google/veo-3",
  duration: 5,
})
// → { jobId, status: "submitted" } — poll: generateVideo({ jobId: job.jobId })

// Text-to-speech (returns base64 audio)
const speech = await atai.speech.speak({
  input: "Hello from Atai!",
  model: "openai/gpt-4o-mini-tts-2025-12-15",
  voice: "alloy",
  response_format: "mp3",
})
// → { audioBase64, mimeType }

// Transcription (speech-to-text; base64 audio in)
const text = await atai.transcribe.transcribe({
  input_audio: { data: audioBase64, format: "wav" },
  model: "openai/whisper-large-v3",
  language: "en",   // optional hint
})
// → { text }

// Vision — multimodal understanding (images, PDFs, audio, video + text)
const answer = await atai.vision.visionInput({
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "What is in this image?" },
      { type: "image_url", image_url: { url: "https://example.com/photo.jpg" } },
      // Also supported: { type: "file", file: { file_data } } for PDFs,
      // { type: "input_audio", input_audio: { data, format } },
      // { type: "video_url", video_url: { url } }
    ],
  }],
})
// → { content, model? }

// Voice — text to speech
const audio = await atai.voice.synthesize({ text: "Hello!", voiceId: "optional" })
// → { audioBase64, mimeType, voiceId, modelId, characters }

// Web search
const found = await atai.search.web({ query: "best coffee in Kampala", limit: 5 })
// → { results: [{ title, url, description? }], creditsUsed? }

// Scrape a public URL
const page = await atai.web.scrape({ url: "https://example.com" })
// → { url, title?, markdown?, links?, truncated?, creditsUsed? }

// Push notification
await atai.notifications.send({ token: deviceToken, title: "New order", body: "Table 4 ordered." })

// Maps
const places = await atai.maps.geocode({ query: "Kampala", limit: 5 })
const rev = await atai.maps.reverseGeocode({ longitude: 32.58, latitude: 0.34 })

// Calendar
const bookings = await atai.calendar.listBookings({ startDate: "2026-10-01", limit: 10 })
await atai.calendar.createBooking({ title: "Consultation", startTime: "2026-10-02T09:00:00Z", endTime: "2026-10-02T10:00:00Z" })

// Vectors — semantic search
await atai.vectors.upsert({ vectors: [{ id: "doc-1", values: embedding, metadata: { page: 1 } }] })
const hits = await atai.vectors.search({ vector: embedding, topK: 5 })
await atai.vectors.delete({ ids: ["doc-1"] })

https://atai.ink/api/runtime/v1

Authorization: Bearer atai_production_xxxxxxxxxxxxxxxx

{
  "ok": true,
  "data": {
    "requestId": "rtreq_…",       // correlation ID — also in x-request-id header
    "capability": "ai.text",
    "operation": "chat",
    "data": {                      // provider-neutral payload
      "id": "gen_…",
      "model": "openai/gpt-5.2",
      "content": "…",
      "finishReason": "stop",
      "usage": { "promptTokens": 14, "completionTokens": 42, "totalTokens": 56 }
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "runtime_rate_limited",
    "message": "Too many requests. Please retry later."
  }
}

import { AtaiError, isAuthenticationError, isRateLimitError } from "@atai-group/sdk"

try {
  await atai.ai.chat({ messages: [{ role: "user", content: "Hello" }] })
} catch (e) {
  if (e instanceof AtaiError) {
    console.error(e.code)       // runtime_* or atai_*
    console.error(e.status)     // e.g. 401, 403, 429, 502
    console.error(e.requestId)  // correlation ID for support

    if (isAuthenticationError(e)) {
      // 401 — the key is missing, invalid, revoked or expired: rotate it.
    } else if (isAuthorizationError(e)) {
      // 403 — the key works but lacks the scope for this capability.
    } else if (isRateLimitError(e)) {
      const waitMs = e.retry?.afterMs  // safe retry metadata when provided
      // back off and retry
    }
  }
}

// app/api/chat/route.ts (server) — the key never leaves the server
import { Atai } from "@atai-group/sdk"

const atai = new Atai({ apiKey: process.env.ATAI_API_KEY! })

export async function POST(req: Request) {
  const { message } = await req.json()
  const result = await atai.ai.chat({
    messages: [{ role: "user", content: message }],
    max_tokens: 500,
  })
  return Response.json({ reply: result.content })
}

import { Atai } from "@atai-group/sdk"

// The key arrives via the secret store as ATAI_API_KEY —
// provisioned automatically at build completion.
const atai = new Atai({ apiKey: process.env.ATAI_API_KEY! })

// Optionally verify the wiring at startup:
const health = await atai.health.check()
if (health.status !== "operational") throw new Error("Atai Runtime not connected")