TanStack
AI
Adapters

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 i @tanstack/ai @tanstack/ai-cohere

Embeddings

ts
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:

ts
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:

ts
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:

ts
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

ts
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:

ts
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

ModelCapabilityDescription
embed-v4.0EmbeddingsMultimodal (text + images), Matryoshka dimensions support
rerank-v3.5RerankingLatest multilingual reranker (recommended)
rerank-english-v3.0RerankingEnglish-optimized reranker
rerank-multilingual-v3.0RerankingMultilingual reranker

Environment Variables

Both adapters read your API key from the environment:

shell
COHERE_API_KEY=your-cohere-api-key
VariableRequiredDescription
COHERE_API_KEYYesYour 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:

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

createCohereEmbedding(model, apiKey, config?)

Same as cohereEmbedding with an explicit API key.

cohereRerank(model, config?)

Creates a rerank adapter using COHERE_API_KEY from the environment.

  • model: one of the rerank models above
  • config.baseUrl: override the API base URL (default https://api.cohere.com)
  • config.headers: extra request headers

createCohereRerank(model, apiKey, config?)

Same as cohereRerank with an explicit API key.

Next Steps

Edit on GitHub
Mistral
ElevenLabs