HKUDS/DeepTutor · error · ValueError

Cohere v1 API does not support multimodal `contents`. Use em

Error message

Cohere v1 API does not support multimodal `contents`. Use embed-v4.0 (v2 API) for multimodal.

What it means

The Cohere embedding adapter's v1 API path only supports plain texts; if the request carries multimodal contents it raises immediately. Multimodal embedding (text+image) requires the v2 API with a multimodal model such as embed-v4.0. This is a hard capability boundary of the v1 endpoint.

Source

Thrown at deeptutor/services/embedding/adapters/cohere.py:74

        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
        headers.update({str(k): str(v) for k, v in self.extra_headers.items()})

        model_name = request.model or self.model
        model_info = self.MODELS_INFO.get(model_name, {})
        # `api_version` is now purely a request-shape selector (v1 vs v2 payload).
        # The URL itself is whatever the user configured. Resolution order:
        #   explicit self.api_version (catalog/env override) → MODELS_INFO entry → "v2"
        api_version = self.api_version or model_info.get("api_version") or "v2"
        dimension = request.dimensions or self.dimensions

        input_type = request.input_type or "search_document"

        if api_version == "v1":
            if request.contents:
                raise ValueError(
                    "Cohere v1 API does not support multimodal `contents`. "
                    "Use embed-v4.0 (v2 API) for multimodal."
                )
            payload = {
                "texts": request.texts,
                "model": model_name,
                "input_type": input_type,
            }

            if not request.truncate:
                payload["truncate"] = "NONE"
        else:
            if request.contents and not bool(model_info.get("multimodal", False)):
                raise ValueError(
                    f"Cohere model '{model_name}' does not support multimodal `contents`."
                )
            payload = {
                "model": model_name,

View on GitHub (pinned to 3e82f13042)

Solutions

Set api_version='v2' and model='embed-v4.0' for multimodal contents
If you only need text, strip request.contents and pass texts only on v1

Example fix

# before
adapter = CohereEmbeddingAdapter(api_version="v1", model="embed-english-v3.0")
await adapter.embed(EmbeddingRequest(contents=[...]))  # ValueError
# after
adapter = CohereEmbeddingAdapter(api_version="v2", model="embed-v4.0")
await adapter.embed(EmbeddingRequest(contents=[...]))

Defensive patterns

Strategy: validation

Validate before calling

def cohere_supports_contents(api_version: str, request: EmbeddingRequest) -> bool:
    return api_version != "v1" or not request.contents

Try / catch

try:
    await adapter.embed(req)
except ValueError as e:
    if "v1 API does not support multimodal" in str(e):
        adapter = CohereEmbeddingAdapter(api_version="v2", model="embed-v4.0")
        return await adapter.embed(req)
    raise

Prevention

Assert api_version=='v2' and a v4 model when building multimodal requests
Centralize provider capability checks in your embedding client factory

When it happens

Trigger: Building an EmbeddingRequest with contents=[...] while the adapter is configured with api_version='v1', then calling embed().

Common situations: Upgrading a text-only pipeline to multimodal without switching api_version to 'v2' and the model to embed-v4.0; defaults pinned to v1 for embed-english-v3.0 while indexing image documents.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/9d42001b823a17d1. Report an issue: GitHub.