Cohere

The Cohere provider contains language and embedding model support for the Cohere chat API. You can use Cohere models through AI Gateway (recommended) or connect directly with @ai-sdk/cohere.

import { generateText } from 'ai';

const { text } = await generateText({
  model: "cohere/command-a",
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

console.log(text);

Using AI Gateway

The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install ai:

$ pnpm add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

Gateway feature and provider-option support depends on the model and the provider serving the request. See Gateway provider options.

Using @ai-sdk/cohere

For direct access to Cohere, install ai and @ai-sdk/cohere:

$ pnpm add ai @ai-sdk/cohere

Set your Cohere API credential in the COHERE_API_KEY environment variable:

export COHERE_API_KEY=your_api_key_here

AI Gateway does not expose every API in @ai-sdk/cohere. Use the direct provider for provider-specific APIs or custom connection settings.

The following sections document the direct @ai-sdk/cohere provider, including its model factories and settings. Gateway model and feature availability can differ.

Provider Instance

You can import the default provider instance cohere from @ai-sdk/cohere:

import { cohere } from '@ai-sdk/cohere';

If you need a customized setup, you can import createCohere from @ai-sdk/cohere and create a provider instance with your settings:

import { createCohere } from '@ai-sdk/cohere';

const cohere = createCohere({
  // custom settings
});

You can use the following optional settings to customize the Cohere provider instance:

  • baseURL string

    Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.cohere.com/v2.

  • apiKey string | PromiseLike<string> | (() => string | PromiseLike<string>)

    Pass a function to resolve credentials before each request, including when keys rotate. The function can return a string or a promise. Credential caching and refresh are managed by the function.

    API key that is being sent using the Authorization header. It defaults to the COHERE_API_KEY environment variable.

  • headers Record<string,string>

    Custom headers to include in the requests.

  • fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

    Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

  • generateId () => string

    Optional function to generate unique IDs for each request. Defaults to the SDK's built-in ID generator.

Language Models

You can create models that call the Cohere chat API using a provider instance. The first argument is the model id, e.g. command-a-03-2025. Some Cohere chat models support tool calls.

const model = cohere('command-a-03-2025');

Example

You can use Cohere language models to generate text with the generateText function:

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

const { text } = await generateText({
  model: cohere('command-a-03-2025'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Cohere language models can also be used in the streamText function and support structured data generation with Output (see AI SDK Core).

Model Capabilities

ModelImage InputObject GenerationTool UsageTool Streaming
command-a-03-2025
command-a-reasoning-08-2025
command-a-vision-07-2025
command-r7b-12-2024
command-r-plus-04-2024
command-r-plus
command-r-08-2024
command-r-03-2024
command-r
command
command-nightly
command-light
command-light-nightly

The table above lists popular models. Please see the Cohere docs for a full list of available models. You can also pass any available provider model ID as a string if needed.

Image Inputs

Vision-capable Cohere models such as command-a-vision-07-2025 accept image inputs as part of the message content. You can pass images as raw bytes, base64-encoded strings, or URLs:

import { cohere } from '@ai-sdk/cohere';
import { generateText } from 'ai';
import { readFileSync } from 'node:fs';

const { text } = await generateText({
  model: cohere('command-a-vision-07-2025'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe the image in detail.' },
        {
          type: 'file',
          mediaType: 'image',
          data: readFileSync('./data/comic-cat.png'),
        },
      ],
    },
  ],
});

You can use the cohere provider option on a file part to set the image input detail to high, low, or auto:

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

const { text } = await generateText({
  model: cohere('command-a-vision-07-2025'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe the image in detail.' },
        {
          type: 'file',
          mediaType: 'image',
          data: 'https://github.com/vercel/ai/blob/main/examples/ai-functions/data/comic-cat.png?raw=true',

          // Cohere specific options - image detail:
          providerOptions: {
            cohere: { detail: 'high' },
          },
        },
      ],
    },
  ],
});

Reasoning

Cohere has introduced reasoning with the command-a-reasoning-08-2025 model. You can learn more at https://docs.cohere.com/docs/reasoning.

import { cohere, type CohereLanguageModelChatOptions } from '@ai-sdk/cohere';
import { generateText } from 'ai';

async function main() {
  const { text, reasoning } = await generateText({
    model: cohere('command-a-reasoning-08-2025'),
    prompt:
      "Alice has 3 brothers and she also has 2 sisters. How many sisters does Alice's brother have?",
    // optional: reasoning options
    providerOptions: {
      cohere: {
        thinking: {
          type: 'enabled',
          tokenBudget: 100,
        },
      } satisfies CohereLanguageModelChatOptions,
    },
  });

  console.log(reasoning);
  console.log(text);
}

main().catch(console.error);

Sources

You can ground a Cohere response in documents by adding text files to the prompt as file parts. When the model cites one of these documents, the provider returns the cited text span as a source.

With generateText, cited documents are available in result.sources:

import { cohere } from '@ai-sdk/cohere';
import { generateText } from 'ai';
import { readFileSync } from 'node:fs';

const model = cohere('command-a-03-2025');

const { text, sources } = await generateText({
  model,
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is the capital of Zephyria?' },
        {
          type: 'file',
          mediaType: 'text/plain',
          filename: 'zephyria.txt',
          data: readFileSync('./data/zephyria.txt'),
        },
      ],
    },
  ],
});

console.log(sources);

With streamText, the same citations are emitted as source stream parts:

import { streamText } from 'ai';

const result = streamText({
  model,
  messages: [
    // same messages as above
  ],
});

for await (const part of result.fullStream) {
  if (part.type === 'source') {
    console.log(part.sourceType); // 'document'
    console.log(part.title);
    console.log(part.providerMetadata?.cohere);
  }
}

Each source has sourceType: 'document', the document title ('Document' when Cohere does not return one), and citation details in providerMetadata.cohere:

  • start / end number - character offsets of the cited text in the response.
  • text string - the cited text.
  • sources array - the raw Cohere sources, including each document's id, text, and title.
  • citationType string - the Cohere citation type, e.g. 'TEXT_CONTENT'.

Keys that Cohere omits are absent from providerMetadata.cohere. Citations that only reference tool output have no document to cite and are not emitted as sources.

Embedding Models

You can create models that call the Cohere embed API using the .embedding() factory method.

const model = cohere.embedding('embed-v4.0');

You can use Cohere embedding models to generate embeddings with the embed function:

import { cohere, type CohereEmbeddingModelOptions } from '@ai-sdk/cohere';
import { embed } from 'ai';

const { embedding } = await embed({
  model: cohere.embedding('embed-v4.0'),
  value: 'sunny day at the beach',
  providerOptions: {
    cohere: {
      inputType: 'search_document',
    } satisfies CohereEmbeddingModelOptions,
  },
});

Cohere embedding models support additional provider options that can be passed via providerOptions.cohere:

import { cohere, type CohereEmbeddingModelOptions } from '@ai-sdk/cohere';
import { embed } from 'ai';

const { embedding } = await embed({
  model: cohere.embedding('embed-v4.0'),
  value: 'sunny day at the beach',
  providerOptions: {
    cohere: {
      inputType: 'search_document',
      truncate: 'END',
    } satisfies CohereEmbeddingModelOptions,
  },
});

The following provider options are available:

  • embeddingType 'float' | 'int8' | 'uint8' | 'binary' | 'ubinary'

    Selects one embedding format per call. Defaults to float, preserving the existing behavior. Non-float formats require Embed v3.0 or newer. For example:

    const { embedding } = await embed({
      model: cohere.embedding('embed-v4.0'),
      value: 'sunny day at the beach',
      providerOptions: {
        cohere: {
          embeddingType: 'int8',
        } satisfies CohereEmbeddingModelOptions,
      },
    });

    The selected format is returned in embedding (or embeddings for embedMany) as number arrays. The provider returns the values without converting or unpacking them. binary and ubinary contain packed bytes: each number represents eight dimensions. Use a binary-aware vector database or unpack the bits before comparing vectors; do not pass packed bytes directly to cosineSimilarity. Compressed formats can affect retrieval quality, and compact storage requires an appropriate database representation.

  • inputType 'search_document' | 'search_query' | 'classification' | 'clustering'

    Specifies the type of input passed to the model. Default is search_query.

    • search_document: Used for embeddings stored in a vector database for search use-cases.
    • search_query: Used for embeddings of search queries run against a vector DB to find relevant documents.
    • classification: Used for embeddings passed through a text classifier.
    • clustering: Used for embeddings run through a clustering algorithm.
  • outputDimension 256 | 512 | 768 | 1024 | 1536 | 2048

    The number of dimensions of the output embedding. Available for Embed v4.0 and newer models. Embed v4.0 supports 256, 512, 1024, and 1536 (default). Embed v5.0 Pro and Fast also support 768 and 2048 (default). When omitted, the API uses the model's default dimension.

  • truncate 'NONE' | 'START' | 'END'

    Specifies how the API will handle inputs longer than the maximum token length. Default is END.

    • NONE: If selected, when the input exceeds the maximum input token length will return an error.
    • START: Will discard the start of the input until the remaining input is exactly the maximum input token length for the model.
    • END: Will discard the end of the input until the remaining input is exactly the maximum input token length for the model.

Model Capabilities

ModelDefault DimensionsSupported DimensionsCustom Dimensions
embed-v5.0-pro2048256, 512, 768, 1024, 1536, 2048
embed-v5.0-fast2048256, 512, 768, 1024, 1536, 2048
embed-v4.01536256, 512, 1024, 1536
embed-english-v3.010241024
embed-multilingual-v3.010241024
embed-english-light-v3.0384384
embed-multilingual-light-v3.0384384
embed-english-v2.040964096
embed-english-light-v2.010241024
embed-multilingual-v2.0768768

Reranking Models

You can create models that call the Cohere rerank API using the .reranking() factory method.

const model = cohere.reranking('rerank-v4.0-pro');

You can use Cohere reranking models to rerank documents with the rerank function:

import { cohere } from '@ai-sdk/cohere';
import { rerank } from 'ai';

const documents = [
  'sunny day at the beach',
  'rainy afternoon in the city',
  'snowy night in the mountains',
];

const { ranking } = await rerank({
  model: cohere.reranking('rerank-v4.0-pro'),
  documents,
  query: 'talk about rain',
  topN: 2,
});

console.log(ranking);
// [
//   { originalIndex: 1, score: 0.9, document: 'rainy afternoon in the city' },
//   { originalIndex: 0, score: 0.3, document: 'sunny day at the beach' }
// ]

Cohere reranking models support additional provider options that can be passed via providerOptions.cohere:

import { cohere, type CohereRerankingModelOptions } from '@ai-sdk/cohere';
import { rerank } from 'ai';

const { ranking } = await rerank({
  model: cohere.reranking('rerank-v4.0-pro'),
  documents: ['sunny day at the beach', 'rainy afternoon in the city'],
  query: 'talk about rain',
  providerOptions: {
    cohere: {
      maxTokensPerDoc: 1000,
      priority: 1,
    } satisfies CohereRerankingModelOptions,
  },
});

The following provider options are available:

  • maxTokensPerDoc number

    Maximum number of tokens per document. Default is 4096.

  • priority number

    Priority of the request. Default is 0.

Model Capabilities

ModelText DocumentsObject DocumentsTop N
rerank-v4.0-proConditional: Objects are converted to JSON strings with a compatibility warning.
rerank-v4.0-fastConditional: Objects are converted to JSON strings with a compatibility warning.
rerank-v3.5Conditional: Objects are converted to JSON strings with a compatibility warning.
rerank-english-v3.0Conditional: Objects are converted to JSON strings with a compatibility warning.
rerank-multilingual-v3.0Conditional: Objects are converted to JSON strings with a compatibility warning.