The Cohere adapter covers the two retrieval steps of a RAG pipeline:
- Embeddings (
cohereEmbedding): turn text, images, and fused text+image inputs into vectors withembed(). - Reranking (
cohereRerank): reorder candidate documents by relevance to a query withrerank().
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#
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:
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 (defaulthttps://api.cohere.com)config.headers: extra request headersconfig.allowUrlFetch: downloadhttp(s)image URLs and inline them as base64 (defaultfalse)
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 aboveconfig.baseUrl: override the API base URL (defaulthttps://api.cohere.com)config.headers: extra request headers
createCohereRerank(model, apiKey, config?)#
Same as cohereRerank with an explicit API key.
Next Steps#
- Embeddings guide: the full
embed()API - Reranking guide: full walkthrough including RAG pipelines
- Generation Hooks: usage and lifecycle middleware