Cohere

The Cohere adapter covers the two retrieval steps of a RAG pipeline:

Embeddings (cohereEmbedding): turn text, images, and fused text+image inputs into vectors with embed().
Reranking (cohereRerank): reorder candidate documents by relevance to a query with rerank().

It does not support chat(), summarize(), or media generation. Use OpenAI, Anthropic, or Gemini for those. The adapter talks to Cohere's HTTP API directly over fetch, with no SDK dependency.

Installation

shell

npm install @tanstack/ai @tanstack/ai-cohere

Embeddings

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);

inputType is required by Cohere's API. Use search_document at index time and search_query at query time (or classification / clustering for those workloads). TanStack AI enforces this at the type level, so modelOptions is required for Cohere embedding calls.

Multimodal Embeddings

embed-v4.0 embeds images alongside text. An image part produces an image vector. A nested array of parts ([textPart, imagePart]) fuses text and image into one vector, which suits product catalogs and screenshot search. The outer array is the item list, so nest to fuse:

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

Cohere's API does not fetch remote image URLs. Pass base64 data (or a data: URI), or opt into adapter-side downloading:

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" },
});

Requesting Dimensions

embed-v4.0 supports Matryoshka output dimensions via the top-level dimensions option:

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" },
});

Reranking

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'

For the full reranking guide, with object documents, RAG pipelines, options, and the result shape, see Reranking.

Per-request rerank options go on 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	Capability	Description
embed-v4.0	Embeddings	Multimodal (text + images), Matryoshka dimensions support
rerank-v3.5	Reranking	Latest multilingual reranker (recommended)
rerank-english-v3.0	Reranking	English-optimized reranker
rerank-multilingual-v3.0	Reranking	Multilingual reranker

Environment Variables

Both adapters read your API key from the environment:

shell

COHERE_API_KEY=your-cohere-api-key

Variable	Required	Description
COHERE_API_KEY	Yes	Your Cohere API key

Get a key from the Cohere dashboard.

Explicit API Keys

To pass a key directly instead of reading 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");

API Reference

cohereEmbedding(model, config?)

Creates an embedding adapter using COHERE_API_KEY from the environment.

model: "embed-v4.0"
config.baseUrl: override the API base URL (default https://api.cohere.com)
config.headers: extra request headers
config.allowUrlFetch: download http(s) image URLs and inline them as base64 (default false)