--- title: Cohere description: Learn how to use Cohere with AI Gateway and the direct provider. url: "https://ai-sdk.dev/providers/ai-sdk-providers/cohere" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). The [Cohere](https://cohere.com/) provider contains language and embedding model support for the Cohere chat API. You can use Cohere models through [AI Gateway](/providers/ai-sdk-providers/ai-gateway) (recommended) or connect directly with `@ai-sdk/cohere`. ```ts provider="cohere" model="cohere/command-a" 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`: ```bash pnpm add ai ``` Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment: ```bash export AI_GATEWAY_API_KEY=your_api_key_here ``` Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments). See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models. Gateway feature and provider-option support depends on the model and the provider serving the request. See [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options). ## Using `@ai-sdk/cohere` For direct access to Cohere, install `ai` and `@ai-sdk/cohere`: ```bash pnpm add ai @ai-sdk/cohere ``` Set your Cohere API credential in the `COHERE_API_KEY` environment variable: ```bash 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`: ```ts 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: ```ts 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* API key that is being sent using the `Authorization` header. It defaults to the `COHERE_API_KEY` environment variable. - **headers** *Record\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/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](https://docs.cohere.com/v2/docs/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. ```ts const model = cohere('command-a-03-2025'); ``` ### Example You can use Cohere language models to generate text with the `generateText` function: ```ts 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`](/docs/reference/ai-sdk-core/output) (see [AI SDK Core](/docs/ai-sdk-core)). ### Model Capabilities | Model | Image Input | Object Generation | Tool Usage | Tool 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](https://docs.cohere.com/v2/docs/models#command) 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: ```ts 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](https://docs.cohere.com/docs/image-inputs) to `high`, `low`, or `auto`: ```ts {2,16-18} 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](https://docs.cohere.com/docs/reasoning). ```ts 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); ``` ## Embedding Models You can create models that call the [Cohere embed API](https://docs.cohere.com/v2/reference/embed) using the `.embedding()` factory method. ```ts const model = cohere.embedding('embed-v4.0'); ``` You can use Cohere embedding models to generate embeddings with the `embed` function: ```ts 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`: ```ts 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: ```ts 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 | Model | Embedding Dimensions | | ------------------------------- | ----------------------------------------- | | `embed-v5.0-pro` | 256, 512, 768, 1024, 1536, 2048 (default) | | `embed-v5.0-fast` | 256, 512, 768, 1024, 1536, 2048 (default) | | `embed-v4.0` | 256, 512, 1024, 1536 (default) | | `embed-english-v3.0` | 1024 | | `embed-multilingual-v3.0` | 1024 | | `embed-english-light-v3.0` | 384 | | `embed-multilingual-light-v3.0` | 384 | | `embed-english-v2.0` | 4096 | | `embed-english-light-v2.0` | 1024 | | `embed-multilingual-v2.0` | 768 | ## Reranking Models You can create models that call the [Cohere rerank API](https://docs.cohere.com/v2/reference/rerank) using the `.reranking()` factory method. ```ts const model = cohere.reranking('rerank-v4.0-pro'); ``` You can use Cohere reranking models to rerank documents with the `rerank` function: ```ts 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`: ```ts 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 | Model | | -------------------------- | | `rerank-v4.0-pro` | | `rerank-v4.0-fast` | | `rerank-v3.5` | | `rerank-english-v3.0` | | `rerank-multilingual-v3.0` | --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)