Migrating from Google Gemini to Anthropic: A Practical Guide

Last updated

Both APIs are non-OpenAI, so this is an involved remap. You convert Gemini’s contents/parts into Claude’s messages, move the system instruction to Claude’s top-level system, and make max_tokens explicit (Claude requires it).

API concept mapping

Gemini native → Anthropic Messages (as of June 2026).
ConceptGemini (native)Anthropic
SDK google-genaianthropic
Auth GEMINI_API_KEYx-api-key + anthropic-version
Call models.generate_contentmessages.create
Turns contents[] (user/model)messages[] (user/assistant)
System prompt config.system_instructiontop-level system param
Max output config.max_output_tokensmax_tokens (required)
Response text response.textcontent[0].text
Tools config.tools (declarations)tools + tool_use blocks

Before / after

Before — Gemini native 
from google import genai
from google.genai import types
client = genai.Client()

resp = client.models.generate_content(
  model="gemini-2.5-flash",
  contents="Explain rate limits in one line.",
  config=types.GenerateContentConfig(system_instruction="You are concise.", max_output_tokens=1024),
)
print(resp.text)
After — Anthropic 
import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
  model="claude-sonnet-4-6",
  max_tokens=1024,                       # required on Anthropic
  system="You are concise.",             # was config.system_instruction
  messages=[{"role": "user", "content": "Explain rate limits in one line."}],
)
print(resp.content[0].text)
Watch for these
  • Role rename: Gemini model → Anthropic assistant.
  • System instruction → top-level system; max_output_tokens → required max_tokens.
  • Response path becomes content[0].text.
  • Tools: Gemini function declarations → Claude tools with input_schema; results come back as tool_use blocks and go in as tool_result blocks in a user message.
  • Handle 529 Overloaded (Anthropic’s capacity signal) in addition to 429.
  • Re-tune prompts and re-run evals.

What to do next

  1. Convert contents → Claude messages (rename model → assistant).
  2. Move the system instruction to top-level system; set a required max_tokens.
  3. Port tool declarations to Claude’s tools/input_schema and the tool_result round-trip.
  4. Re-price with the cost calculator; reverse route is Anthropic → Gemini. The Claude target mechanics match OpenAI → Anthropic.

Frequently asked questions

What makes Gemini → Anthropic involved?
Neither side is OpenAI-shaped, so there's no compatibility shortcut for the whole flow. You remap Gemini's contents/parts to Claude's messages, move the system instruction to the top-level system, and add a required max_tokens.
How do roles and the response differ?
Gemini's assistant role is model (becomes Anthropic assistant), and you read content[0].text on Claude instead of response.text.
Anything new to handle on Claude?
Yes — Claude can return 529 Overloaded when its API is at capacity, separate from 429 rate limits. Add backoff for both, and remember max_tokens is mandatory.