Groq API TypeScript SDK

1.1.2 · active · verified Sun Apr 19

The `groq-sdk` package provides the official TypeScript library for interacting with the Groq API, offering convenient access to Groq's REST API from both server-side TypeScript and JavaScript environments. It is currently at stable version `1.1.2`, released on 2026-03-25. The library exhibits a rapid release cadence, with frequent minor versions and patches, often coinciding with updates to the underlying Groq API. Key differentiators include comprehensive TypeScript support with precise type definitions for all request parameters and response fields, ensuring a robust and type-safe development experience. The SDK is generated using Stainless and includes extensive documentation via docstrings. It supports various methods for file uploads, including `File` instances, `fs.ReadStream`, `fetch` `Response` objects, and a dedicated `toFile` helper for diverse environments.

Common errors

```
Error: Missing API Key. Pass `apiKey` to the client constructor or set the `GROQ_API_KEY` environment variable.
```
cause The Groq client was instantiated without a valid API key provided through `apiKey` in the constructor or the `GROQ_API_KEY` environment variable.

fix Set the `GROQ_API_KEY` environment variable (e.g., `export GROQ_API_KEY='sk-...'`) or explicitly pass `apiKey: 'YOUR_SECRET_KEY'` to the `Groq` client constructor.
```
TypeError: Groq is not a constructor
```
cause Attempting to instantiate the `Groq` client using CommonJS `require` syntax in an environment expecting ESM (e.g., modern Node.js module types or bundlers).

fix Change your import statement from `const Groq = require('groq-sdk');` to `import Groq from 'groq-sdk';`.
```
API Error: 401 - UnauthorizedError
```
cause The provided API key is invalid or expired, leading to an authentication failure with the Groq API.

fix Verify that your `GROQ_API_KEY` is correct, active, and has the necessary permissions. Regenerate the key if necessary from the Groq console.

Warnings

breaking Version `1.0.0` included a significant 'TS migration' which may introduce breaking changes, especially for users upgrading from pre-1.0.0 versions that might have relied on different internal structures or JavaScript-specific patterns. Review the `v1.0.0` changelog carefully for migration paths.
Fix: Thoroughly review the official migration guides and documentation for `v1.0.0` when upgrading from versions prior to `1.0.0`. Update import statements and object structures as necessary.
gotcha The Groq API key (GROQ_API_KEY) must be provided, either directly in the client configuration or via the `GROQ_API_KEY` environment variable. Failure to provide it will result in authentication errors.
Fix: Ensure `process.env['GROQ_API_KEY']` is correctly set, or pass the `apiKey` property directly to the `Groq` client constructor: `new Groq({ apiKey: 'YOUR_API_KEY' })`.
gotcha This SDK primarily targets modern JavaScript/TypeScript environments that support ESM imports. While transpilers can handle CommonJS `require` for some cases, it's best practice to use `import` statements to avoid potential module resolution issues, especially with TypeScript types.
Fix: Use `import Groq from 'groq-sdk';` instead of `const Groq = require('groq-sdk');` for all module imports to ensure compatibility and correct type inference.

Install

npm install groq-sdk npm
yarn add groq-sdk yarn
pnpm add groq-sdk pnpm

Imports

Groq
wrong:
```
const Groq = require('groq-sdk');
```
correct:
```
import Groq from 'groq-sdk';
```
The primary client is a default export. The library is primarily ESM-first, so CommonJS `require` is generally discouraged and may lead to issues.
Groq.Chat.CompletionCreateParams
```
import Groq from 'groq-sdk';
// ... then use Groq.Chat.CompletionCreateParams
```
Type definitions are nested under the `Groq` namespace, allowing direct access like `Groq.Chat.ChatCompletion` or `Groq.Chat.CompletionCreateParams` after importing the main client.
toFile
wrong:
```
import Groq, { toFile } from 'groq-sdk'; // Common but slightly less precise if only needing toFile
```
correct:
```
import { toFile } from 'groq-sdk';
```
The `toFile` utility is a named export, useful for converting various data sources into file-like objects for API uploads.

Quickstart

This quickstart initializes the Groq client with an API key from environment variables and sends a chat completion request to an LLM, including basic error handling for API-specific errors.

import Groq from 'groq-sdk';

const client = new Groq({
  apiKey: process.env['GROQ_API_KEY'] ?? '', // Ensure GROQ_API_KEY is set in your environment
});

async function main() {
  try {
    const chatCompletion = await client.chat.completions.create({
      messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        { role: 'user', content: 'Explain the importance of low latency LLMs' }
      ],
      model: 'llama3-8b-8192', // Replace with a valid Groq model, e.g., 'llama3-8b-8192'
      temperature: 0.7,
      max_tokens: 1024
    });

    console.log(`Completion ID: ${chatCompletion.id}`);
    console.log(`First choice message: ${chatCompletion.choices[0]?.message?.content}`);
  } catch (error) {
    if (error instanceof Groq.APIError) {
      console.error(`API Error: ${error.status} - ${error.name}: ${error.message}`);
      console.error('Headers:', error.headers);
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

main();

view raw JSON →