{"record":{"id":"9d42001b823a17d1","repo":"HKUDS/DeepTutor","slug":"cohere-v1-api-does-not-support-multimodal-content","errorCode":null,"errorMessage":"Cohere v1 API does not support multimodal `contents`. Use embed-v4.0 (v2 API) for multimodal.","messagePattern":"Cohere v1 API does not support multimodal `contents`\\. Use embed-v4\\.0 \\(v2 API\\) for multimodal\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/embedding/adapters/cohere.py","lineNumber":74,"sourceCode":"        headers = {\n            \"Authorization\": f\"Bearer {self.api_key}\",\n            \"Content-Type\": \"application/json\",\n        }\n        headers.update({str(k): str(v) for k, v in self.extra_headers.items()})\n\n        model_name = request.model or self.model\n        model_info = self.MODELS_INFO.get(model_name, {})\n        # `api_version` is now purely a request-shape selector (v1 vs v2 payload).\n        # The URL itself is whatever the user configured. Resolution order:\n        #   explicit self.api_version (catalog/env override) → MODELS_INFO entry → \"v2\"\n        api_version = self.api_version or model_info.get(\"api_version\") or \"v2\"\n        dimension = request.dimensions or self.dimensions\n\n        input_type = request.input_type or \"search_document\"\n\n        if api_version == \"v1\":\n            if request.contents:\n                raise ValueError(\n                    \"Cohere v1 API does not support multimodal `contents`. \"\n                    \"Use embed-v4.0 (v2 API) for multimodal.\"\n                )\n            payload = {\n                \"texts\": request.texts,\n                \"model\": model_name,\n                \"input_type\": input_type,\n            }\n\n            if not request.truncate:\n                payload[\"truncate\"] = \"NONE\"\n        else:\n            if request.contents and not bool(model_info.get(\"multimodal\", False)):\n                raise ValueError(\n                    f\"Cohere model '{model_name}' does not support multimodal `contents`.\"\n                )\n            payload = {\n                \"model\": model_name,","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/embedding/adapters/cohere.py#L56-L92","documentation":"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.","triggerScenarios":"Building an EmbeddingRequest with contents=[...] while the adapter is configured with api_version='v1', then calling embed().","commonSituations":"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.","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"],"exampleFix":"# before\nadapter = CohereEmbeddingAdapter(api_version=\"v1\", model=\"embed-english-v3.0\")\nawait adapter.embed(EmbeddingRequest(contents=[...]))  # ValueError\n# after\nadapter = CohereEmbeddingAdapter(api_version=\"v2\", model=\"embed-v4.0\")\nawait adapter.embed(EmbeddingRequest(contents=[...]))","handlingStrategy":"validation","validationCode":"def cohere_supports_contents(api_version: str, request: EmbeddingRequest) -> bool:\n    return api_version != \"v1\" or not request.contents","typeGuard":null,"tryCatchPattern":"try:\n    await adapter.embed(req)\nexcept ValueError as e:\n    if \"v1 API does not support multimodal\" in str(e):\n        adapter = CohereEmbeddingAdapter(api_version=\"v2\", model=\"embed-v4.0\")\n        return await adapter.embed(req)\n    raise","preventionTips":["Assert api_version=='v2' and a v4 model when building multimodal requests","Centralize provider capability checks in your embedding client factory"],"tags":["cohere","embeddings","multimodal","api-version"],"backgroundTag":"api-version-capability-mismatch","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}