Docs/Tutorials/Node.js quickstart
Beginner~5 minNode.jsTypeScript

Node.js SDK Quickstart

Cloudach is OpenAI-compatible. You use the official openai npm package — just point it at Cloudach's base URL. No new SDK to learn. Works with ESM, CommonJS, and TypeScript.

1. Install

Install the OpenAI SDK (v4 or later):

npm install openai

Or with yarn / pnpm:

yarn add openai
# or
pnpm add openai

2. Configure

Create the client with your Cloudach API key and base URL. Store your key in an environment variable — never commit it to source control.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.cloudach.com/v1",
  apiKey: process.env.CLOUDACH_API_KEY,
});
Your key looks like sk-cloudach-.... Get one from the Dashboard → API Keys page. For local development, put it in a .env file and load it with dotenv.

3. First call

Make your first chat completion — 5 lines of logic:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.cloudach.com/v1",
  apiKey: process.env.CLOUDACH_API_KEY,
});

const response = await client.chat.completions.create({
  model: "llama3-8b",
  messages: [{ role: "user", content: "What is the capital of France?" }],
});

console.log(response.choices[0].message.content);
// → "The capital of France is Paris."
console.log(`Tokens used: ${response.usage.total_tokens}`);

Run it (Node.js 18+ with ESM or top-level await):

CLOUDACH_API_KEY=sk-cloudach-... node --input-type=module < your_script.js

Or with a package.json that has "type": "module":

CLOUDACH_API_KEY=sk-cloudach-... node your_script.js

4. Add a system prompt

Use the system role to give the model a persona or instructions. It always comes first in the messages array.

const response = await client.chat.completions.create({
  model: "llama3-8b",
  messages: [
    { role: "system", content: "You are a concise technical assistant. Reply in plain text only." },
    { role: "user",   content: "Explain what a REST API is in one sentence." },
  ],
});

console.log(response.choices[0].message.content);

5. Key parameters

The most useful parameters for chat.completions.create:

ParameterTypeDefaultDescription
modelstring—Required. Model ID, e.g. "llama3-8b", "mixtral-8x7b"
messagesarray—Required. Array of {role, content} objects
temperaturenumber1.0Randomness: 0.0 = deterministic, 2.0 = very random
max_tokensnumbermodel maxHard cap on response length in tokens
streambooleanfalseSet true to receive tokens as they are generated
top_pnumber1.0Nucleus sampling threshold (alternative to temperature)
const response = await client.chat.completions.create({
  model: "llama3-70b",
  messages: [{ role: "user", content: "Write a haiku about distributed systems." }],
  temperature: 0.8,
  max_tokens: 100,
});

6. Streaming

Set stream: true to receive tokens as they are generated. Use for await...of to iterate over the stream.

const stream = await client.chat.completions.create({
  model: "llama3-8b",
  messages: [{ role: "user", content: "Count from 1 to 5 slowly." }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

process.stdout.write("\n");
Streaming dramatically improves perceived latency — users see the first token in ~1s instead of waiting for the full response. Essential for any chat UI.

TypeScript

The openai package ships its own TypeScript types. No @types/openai needed.

import OpenAI from "openai";
import type { ChatCompletion, ChatCompletionChunk } from "openai/resources";

const client = new OpenAI({
  baseURL: "https://api.cloudach.com/v1",
  apiKey: process.env.CLOUDACH_API_KEY!,
});

// Non-streaming — strongly typed response
const response: ChatCompletion = await client.chat.completions.create({
  model: "llama3-8b",
  messages: [{ role: "user", content: "Hello!" }],
});

// Streaming — each chunk is ChatCompletionChunk
const stream = await client.chat.completions.create({
  model: "llama3-8b",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta: string | null = chunk.choices[0]?.delta?.content ?? null;
  if (delta) process.stdout.write(delta);
}

Next steps