Project setup

1. Copy the source/ directory into your project, for example at src/groq-sdk/.

2. In tsconfig.json, ensure moduleResolution is node16, bundler, or nodenext and target is at minimum ES2018:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true
  }
}

3. Add a path alias if desired (optional):

{
  "compilerOptions": {
    "paths": {
      "groq-sdk": ["./src/groq-sdk/index.ts"],
      "groq-sdk/*": ["./src/groq-sdk/*"]
    }
  }
}

4. Set your API key as an environment variable:

export GROQ_API_KEY=your_key_here

5. Import from the local source root:

import Groq from './src/groq-sdk/index';

Public API

Groq

import Groq, { type ClientOptions } from './src/groq-sdk/index';

const client = new Groq({
  apiKey: string;            // defaults to process.env['GROQ_API_KEY']
  baseURL?: string;          // override the API base URL
  timeout?: number;          // request timeout in milliseconds
  maxRetries?: number;       // automatic retry count (default 2)
  defaultHeaders?: HeadersLike;
  defaultQuery?: Record<string, unknown>;
});

The main entry point. Instantiate once per process and reuse. Exposes .chat, .audio, .embeddings, .files, .models, .batches, and .completions sub-resources.

APIPromise

import { APIPromise } from './src/groq-sdk/core/api-promise';

All resource methods return an APIPromise<T> which extends a standard Promise<T>. You can await it directly, or call .withResponse() to get both the parsed body and the raw Response, or .asResponse() to get only the raw Response.

APIError and subclasses

import {
  APIError,
  BadRequestError,
  AuthenticationError,
  PermissionDeniedError,
  NotFoundError,
  RateLimitError,
  InternalServerError,
  APIConnectionError,
  APIConnectionTimeoutError,
  APIUserAbortError,
} from './src/groq-sdk/core/error';

Thrown automatically when the API returns a non-2xx status or the network fails. Check err.status, err.message, and err.headers. Use the typed subclasses for fine-grained catch branching.

toFile

import { toFile, type Uploadable } from './src/groq-sdk/core/uploads';

const file = await toFile(Buffer.from(bytes), 'audio.wav', { type: 'audio/wav' });

Converts Buffer, Uint8Array, ReadableStream, or Response into an Uploadable that any file-upload parameter accepts. Use this when you do not have a native File or fs.ReadStream available.

Working examples

Scenario - Chat completion with typed params

Send a multi-turn conversation and receive a fully-typed response. Demonstrates the canonical usage pattern recommended in the README.

import Groq from './src/groq-sdk/index';
import type { Chat } from './src/groq-sdk/resources/chat/index';

const client = new Groq({ apiKey: process.env.GROQ_API_KEY });

const params: Chat.CompletionCreateParams = {
  model: 'llama3-8b-8192',
  messages: [
    { role: 'system', content: 'You are a concise assistant.' },
    { role: 'user', content: 'What is low latency inference?' },
  ],
  temperature: 0.7,
  max_tokens: 256,
};

const completion: Chat.ChatCompletion = await client.chat.completions.create(params);
console.log(completion.choices[0].message.content);
console.log('tokens used:', completion.usage?.total_tokens);

Scenario - Audio transcription from a file on disk

Transcribe a local audio file using Whisper. The file parameter accepts an fs.ReadStream, a File, a fetch Response, or the output of toFile.

import fs from 'fs';
import Groq from './src/groq-sdk/index';
import type { Transcription, TranscriptionCreateParams } from './src/groq-sdk/resources/audio/index';

const client = new Groq({ apiKey: process.env.GROQ_API_KEY });

const params: TranscriptionCreateParams = {
  model: 'whisper-large-v3-turbo',
  file: fs.createReadStream('/path/to/recording.mp3'),
  language: 'en',
  response_format: 'json',
};

const result: Transcription = await client.audio.transcriptions.create(params);
console.log(result.text);

Scenario - Handling API errors with typed subclasses

Wrap any API call in a try/catch and branch on the specific error subclass or status code.

import Groq, { APIError, RateLimitError, AuthenticationError } from './src/groq-sdk/index';

const client = new Groq({ apiKey: process.env.GROQ_API_KEY });

try {
  const models = await client.models.list();
  for (const model of models.data) {
    console.log(model.id, model.created);
  }
} catch (err) {
  if (err instanceof RateLimitError) {
    console.error('Rate limited. Retry after back-off.');
  } else if (err instanceof AuthenticationError) {
    console.error('Invalid API key. Check GROQ_API_KEY.');
  } else if (err instanceof APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
  } else {
    throw err;
  }
}

Scenario - Creating an embedding

import Groq from './src/groq-sdk/index';
import type { CreateEmbeddingResponse, EmbeddingCreateParams } from './src/groq-sdk/resources/index';

const client = new Groq({ apiKey: process.env.GROQ_API_KEY });

const params: EmbeddingCreateParams = {
  model: 'text-embedding-ada-002',
  input: 'The quick brown fox',
};

const response: CreateEmbeddingResponse = await client.embeddings.create(params);
console.log('embedding length:', response.data[0].embedding.length);

File walkthrough

• client.ts - Defines Groq class and ClientOptions. All HTTP logic, retry, timeout, and auth headers live here.
• index.ts - Package entry point; re-exports Groq (default), APIPromise, toFile, all error classes.
• resource.ts - Minimal APIResource base that holds a back-reference to the client instance.
• resources.ts - Convenience barrel that re-exports everything from resources/index.ts.
• error.ts - Thin re-export shim pointing to core/error.ts.
• uploads.ts - Thin re-export shim pointing to core/uploads.ts.
• api-promise.ts - Thin re-export shim pointing to core/api-promise.ts.
• version.ts - Exports the VERSION string constant ("1.1.2").
• core/api-promise.ts - APIPromise<T> implementation with .withResponse() and .asResponse().
• core/error.ts - All typed error classes (APIError and subclasses keyed by HTTP status).
• core/resource.ts - Base resource class implementation.
• core/streaming.ts - Server-sent event / streaming response handling.
• core/uploads.ts - toFile helper and Uploadable type.
• internal/ - Platform detection, header building, request options, query serialisation, logging, shims, and type utilities. Not intended for direct consumption.
• lib/streaming.ts - Higher-level streaming utilities exposed to resource implementations.
• resources/audio/ - Audio, Speech, Transcriptions, Translations classes + param/response types.
• resources/chat/ - Chat, Completions classes + all ChatCompletion* types.
• resources/batches.ts - Batches resource for async batch job management.
• resources/completions.ts - Completions resource and CompletionUsage type.
• resources/embeddings.ts - Embeddings resource and related types.
• resources/files.ts - Files resource for uploading and managing files.
• resources/models.ts - Models resource for listing and retrieving available models.
• resources/shared.ts - Shared type definitions used across multiple resources.
• resources/index.ts - Barrel re-export of every resource and type.

Common pitfalls and fixes

• Missing GROQ_API_KEY at runtime: The client throws AuthenticationError (401) rather than failing at construction if the key is invalid; set the env var before starting the process, not just in .env files that are not loaded automatically.
• fetch not available in Node < 18: Either upgrade to Node 18+ or set globalThis.fetch before importing the client; the SDK relies on the global fetch.
• ESM/CJS interop: If your project uses "type": "module" in package.json, ensure tsconfig uses "module": "NodeNext" and all local imports use explicit .js extensions when compiling.
• toFile with Buffer in Edge runtimes: Edge runtimes (Cloudflare Workers, Vercel Edge) do not have Node's Buffer; use Uint8Array or a native Blob instead.
• Streaming responses: Do not await the full response when using stream: true; consume the ReadableStream via the async iterator exposed by core/streaming.ts or you will exhaust memory on large outputs.
• Retry storms under rate limits: Default maxRetries is 2. In high-throughput services, set maxRetries: 0 and implement your own back-off to avoid amplifying 429 errors.

Vibe-coding prompt template

I have vendored the Groq TypeScript SDK source at `source/` in my project.
There is a `USAGE.md` at the root of this block that documents the real exports
and file layout. The upstream npm package is `user@example.com`.

Please help me integrate the SDK into my existing project step-by-step:

1. Read `USAGE.md` to understand the file layout and exported symbols.
2. Confirm the correct import path based on where I placed `source/` (I will tell you).
3. Instantiate the `Groq` client with my `GROQ_API_KEY` environment variable.
4. Add a chat completion call using `client.chat.completions.create` with typed params.
5. Add error handling using `APIError` and its subclasses from `source/core/error.ts`.
6. Show me how to add audio transcription using `client.audio.transcriptions.create`.
7. Do not install the `groq-sdk` npm package; import only from the local `source/` path.
8. Show all TypeScript types explicitly so I can see what fields are available.

My project is a Node.js/TypeScript Express app. Here is my current tsconfig: [paste yours].

License and credit

The SDK is generated by Stainless from the Groq OpenAPI spec and is published by Groq under the MIT License (see source/LICENSE if present). Upstream package: groq-sdk on npm. API reference: console.groq.com/docs.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.