Cohere

The Cohere adapter embeds text and images, and it reranks documents for a query. This package has no chat(), summarize(), or media generation.

For those, use OpenAI, Anthropic, or Gemini. The adapter calls the HTTP API of Cohere with fetch, with no SDK dependency.

1. Install

shell

npm i @tanstack/ai @tanstack/ai-cohere

shell

pnpm add @tanstack/ai @tanstack/ai-cohere

shell

yarn add @tanstack/ai @tanstack/ai-cohere

shell

bun add @tanstack/ai @tanstack/ai-cohere

2. Set the API key

Get a key from the Cohere dashboard. Put it in the environment of your server:

shell

COHERE_API_KEY=your-cohere-api-key

cohereEmbedding and cohereRerank read COHERE_API_KEY. To pass the key in code, see Explicit API keys.

3. Embed documents

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const result = await embed({
  adapter: cohereEmbedding("embed-v4.0"),
  input: ["a red guitar", "a blue drum kit"],
  modelOptions: { inputType: "search_document" },
});

console.log(result.embeddings[0]?.vector);
console.log(result.usage?.promptTokens);

The Cohere API requires inputType, and the types require modelOptions on every Cohere embedding call:

search_document: when you index documents.
search_query: when you embed the search query.
classification or clustering: for those workloads.

4. Rerank results

import { rerank } from "@tanstack/ai";
import { cohereRerank } from "@tanstack/ai-cohere";

const { rerankedDocuments } = await rerank({
  adapter: cohereRerank("rerank-v3.5"),
  query: "talk about rain",
  documents: ["sunny day at the beach", "rainy afternoon in the city"],
});

console.log(rerankedDocuments[0]); // 'rainy afternoon in the city'

You now have both retrieval steps. For object documents, RAG pipelines, the options, and the result shape, see Reranking.

Multimodal embeddings

embed-v4.0 embeds images next to text:

An image part gives an image vector.
A nested array of parts ([textPart, imagePart]) joins text and image into one vector. Use it for product catalogs and screenshot search.

The outer array is the list of items, so nest the parts to join them:

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const productPhoto = "iVBORw0KGgo..."; // base64 image data

const result = await embed({
  adapter: cohereEmbedding("embed-v4.0"),
  input: [
    {
      type: "image",
      source: {
        type: "data",
        value: productPhoto,
        mimeType: "image/png",
      },
    },
    // A nested array fuses its parts into a single vector.
    [
      { type: "text", content: "Fender Stratocaster, sunburst finish" },
      {
        type: "image",
        source: {
          type: "data",
          value: productPhoto,
          mimeType: "image/png",
        },
      },
    ],
  ],
  modelOptions: { inputType: "search_document" },
});

console.log(result.embeddings.length); // 2

The Cohere API does not fetch remote image URLs. Pass base64 data (or a data: URI), or turn on downloads in the adapter.

Shorter vectors

embed-v4.0 takes the top-level dimensions option (256, 512, 1024, or 1536):

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const result = await embed({
  adapter: cohereEmbedding("embed-v4.0"),
  input: "a red guitar",
  dimensions: 1024, // 256 | 512 | 1024 | 1536
  modelOptions: { inputType: "search_document" },
});

Rerank options

Rerank options for one request go in modelOptions:

import { rerank } from "@tanstack/ai";
import { cohereRerank } from "@tanstack/ai-cohere";

const { ranking } = await rerank({
  adapter: cohereRerank("rerank-v3.5"),
  query: "refund policy",
  documents: ["Returns accepted within 30 days.", "Free shipping over $50."],
  modelOptions: {
    maxTokensPerDoc: 512, // Cap tokens kept per document (Cohere default: 4096)
  },
});

console.log(ranking);

Models

Model	Activity	Notes
embed-v4.0	Embeddings	Text and images, dimensions support
rerank-v3.5	Reranking	Newest multilingual reranker. Recommended
rerank-english-v3.0	Reranking	Tuned for English
rerank-multilingual-v3.0	Reranking	Multilingual reranker

Advanced

Explicit API keys

To pass a key in code, not from the environment, use the create* factories:

import {
  createCohereEmbedding,
  createCohereRerank,
} from "@tanstack/ai-cohere";

const embedAdapter = createCohereEmbedding(
  "embed-v4.0",
  process.env.MY_COHERE_KEY!,
);
const rerankAdapter = createCohereRerank("rerank-v3.5", "your-cohere-api-key");

Image URLs

To let the adapter download http(s) image URLs and send them as base64, set allowUrlFetch:

import { embed } from "@tanstack/ai";
import { cohereEmbedding } from "@tanstack/ai-cohere";

const adapter = cohereEmbedding("embed-v4.0", { allowUrlFetch: true });

const result = await embed({
  adapter,
  input: {
    type: "image",
    source: { type: "url", value: "https://example.com/guitar.png" },
  },
  modelOptions: { inputType: "search_document" },
});

Behind a proxy

Send every request through a gateway, such as Cloudflare AI Gateway or a corporate proxy, with baseURL and defaultHeaders. These two option names are the same on every TanStack AI adapter, so one gateway config works for all of them.

import { createCohereEmbedding } from "@tanstack/ai-cohere";

const adapter = createCohereEmbedding("embed-v4.0", process.env.COHERE_API_KEY!, {
  baseURL: "https://gateway.example.com/cohere",
  defaultHeaders: { "cf-aig-authorization": `Bearer ${process.env.GATEWAY_TOKEN}` },
});

baseUrl and headers are aliases of the same two options. If you set both forms, baseURL and defaultHeaders win.

API reference

Factory	Creates
cohereEmbedding(model, config?)	Embedding adapter. Reads COHERE_API_KEY
createCohereEmbedding(model, apiKey, config?)	Embedding adapter with an explicit API key
cohereRerank(model, config?)	Rerank adapter. Reads COHERE_API_KEY
createCohereRerank(model, apiKey, config?)	Rerank adapter with an explicit API key

Config for both adapters:

config.baseURL: the API base URL (default https://api.cohere.com). baseUrl is an alias.
config.defaultHeaders: extra request headers. headers is an alias.
config.allowUrlFetch (embeddings only): download http(s) image URLs and send them as base64. Default false.

For the full APIs, see the Embeddings guide, the Reranking guide, and Generation Hooks for usage and lifecycle middleware.