Cohere Python SDK

5.20.4 · active · verified Sat Feb 28

Official Python SDK for Cohere API. Has two coexisting client classes: Client (v1, legacy) and ClientV2 (v2, current). Most LLM-generated code uses v1 patterns. The Generate endpoint is deprecated. model is now required in all v2 calls.

Warnings

breaking Generate endpoint (co.generate()) deprecated as of Aug 26, 2025. Calls will fail after sunset.
Fix: Migrate to co.chat() with ClientV2. See https://docs.cohere.com/v1/docs/migrating-from-cogenerate-to-cochat
breaking model is a required parameter in all v2 API calls. Omitting it raises an error. v1 had a default model fallback.
Fix: Always pass model= explicitly. Current recommended: command-a-03-2025
breaking preamble parameter removed in v2. System instructions must be passed as a system role message.
Fix: Replace preamble='...' with messages=[{'role': 'system', 'content': '...'}, ...]
breaking conversation_id removed in v2. Cohere no longer manages chat history server-side.
Fix: Manage conversation history client-side by passing full messages array each turn
breaking connectors (built-in RAG) removed in v2. Web search now requires passing a web search tool explicitly.
Fix: Implement web search as a tool_use pattern. See v2 migration guide.
breaking rerank v2 deprecated. Use rerank v3.5.
Fix: Update rerank calls to use v3.5 endpoint. Check SDK release notes for exact method changes.
gotcha Response text access changed between v1 and v2. v1: response.text. v2: response.message.content[0].text. Mixing clients and response patterns is the most common error.
Fix: Check which client you instantiated (Client vs ClientV2) and use the matching response access pattern.
gotcha num_generations, stop_sequences, logit_bias, and truncate parameters from Generate are not supported in Chat. No direct equivalent for num_generations.
Fix: For num_generations=n, call co.chat() n times. Trim outputs on your side instead of stop_sequences.
gotcha CO_API_KEY is the expected environment variable name. Not COHERE_API_KEY. Using the wrong var name results in silent auth failure.
Fix: Set export CO_API_KEY=your_key. ClientV2() reads this automatically.

Install

pip install cohere pip
uv add cohere uv

Imports

ClientV2
```
import cohere; co = cohere.ClientV2()
```
Client() is v1 (legacy). ClientV2() is v2 (current). Use ClientV2 for all new code. Both exist in the same package.
response text (v2)
```
response.message.content[0].text
```
v1 Client returns response.text directly. v2 ClientV2 returns response.message.content[0].text — extra nesting.
system prompt (v2)
```
messages=[{'role': 'system', 'content': '...'}, {'role': 'user', 'content': '...'}]
```
preamble parameter removed in v2. Use a system role message at the start of the messages array instead.
AsyncClientV2
```
import cohere; co = cohere.AsyncClientV2()
```
AsyncClient is v1. AsyncClientV2 is the async v2 client.

Quickstart

Minimal chat completion using v2 client

import cohere

co = cohere.ClientV2()  # reads CO_API_KEY env var

response = co.chat(
    model='command-a-03-2025',
    messages=[{'role': 'user', 'content': 'Hello'}]
)
print(response.message.content[0].text)

view raw JSON →