Postupná migrace na Responses API
Na této stránce
Aktualizováno 3. listopadu 2026: Mapování parametrů dříve uvádělo, že
max_tokenssi v Responses API zachovává svůj název; tabulka xAI jej mění namax_output_tokensa názvy se mění i u počítadel využití. Zdroj: Srovnání s Chat Completions.
Proč a kdy migrovat
Koncový bod Chat Completions je označen jako zastaralý (legacy). Bude sice nadále fungovat, ale nebudou do něj přidávány nové funkce. Pokud tvoje aplikace potřebuje serverové nástroje (vyhledávání na webu, spouštění kódu), ukládání konverzací nebo šifrované uvažování, stává se migrace na Responses API nezbytnou.
Dobrá zpráva: tato migrace může probíhat postupně. Nemusíš přepisovat vše najednou.
Krok 1: Identifikuj funkce, které používáš
Než začneš migrovat, udělej si inventuru toho, co tvoje aplikace využívá v rámci Chat Completions:
# Audituj svůj stávající kód
# Hledej tyto vzory:
# 1. Základní volání (prostý text)
client.chat.completions.create(model=..., messages=...)
# 2. Streamování
client.chat.completions.create(..., stream=True)
# 3. Volání funkcí
client.chat.completions.create(..., tools=[...])
# 4. Vize (obrázky)
# zprávy s obsahem jako pole [text, image_url]
# 5. Parametry generování
# temperature, max_tokens, top_p, stop, seed
Základní volání a streamování jsou nejjednodušší na migraci. Volání funkcí vyžaduje úpravu formátu. Vize funguje podobně.
Krok 2: Migruj základní volání
Migrace jednoduchého volání následuje tento vzor:
# PŘED — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# PO — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Mapování polí
Hlavní změny jsou:
messagess rolísystem→instructions(vyhrazený parametr)messagess rolíuser→input(prostý řetězec)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, podle mapovací tabulky xAI;temperaturesi zachovává svůj názevresponse.usage.prompt_tokensacompletion_tokens→input_tokensaoutput_tokens(podrobnosti:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Krok 3: Migruj vícekolové konverzace
Zde Responses API věci zjednodušuje. Místo toho, abys při každém požadavku znovu sestavoval historii, řadíš je za sebou pomocí ID:
# PŘED — Chat Completions (spravuj historii sám)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# PO — Responses API (historii spravuje server)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
Kód je jednodušší a už nemusíš ručně spravovat pole zpráv.
Krok 4: Využij nové funkce
Jakmile provedeš migraci, můžeš využít funkce exclusive pro Responses API:
Vestavěné vyhledávání na webu
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# Odpověď zahrnuje citace s URL zdroji
Ukládání odpovědí
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Uchová po dobu 30 dnů
)
# Získání později
stored = client.responses.retrieve(response.id)
Šifrované uvažování
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# Šifrované uvažování lze znovu využít v následných požadavcích
Doporučená strategie migrace
Místo migrace všeho najednou postupuj krok za krokem:
- Identifikuj volání Chat Completions ve svém kódu
- Rozděľ je podle složitosti (základní → streamování → volání funkcí)
- Nejprve migruj nové koncové body nebo funkce (greenfield)
- Poté migruj nejjednodušší stávající volání
- Ponech Chat Completions pro integrace třetích stran, které to vyžadují (LangChain atd.)
Dočasná koexistence
Během přechodu je zcela přijatelné provozovat oba koncové body souběžně:
# Wrapper, který abstrahuje použitý koncový bod
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Tento přístup ti umožňuje postupný přechod testováním každé migrace jednotlivě.
Klíčové poznatky
- Migrace může být postupná: není třeba přepisovat vše najednou
- Hlavní změny:
messages→input/instructions,choices[0].message.content→output_text - Vícekolové konverzace přecházejí z pole zpráv na jednoduché
previous_response_id - Responses API poskytuje přístup k exkluzivním funkcím (web_search, ukládání, šifrované uvažování)
- Během přechodu provozuj oba koncové body souběžně a migruj podle pořadí složitosti
Otestuj své znalosti
Zastaralé API pochopeno – migrace připravena.
1. Co znamená status legacy a stateless u Chat Completions?
Odpověď: Koncový bod zůstává podporován, ale již se nevyvíjí: jako stateless vyžaduje při každém volání opětovné odeslání celé historie – Responses API je moderní cestou.
2. Které role strukturuji zprávy?
Odpověď: system (a developer), user, assistant – rámec, požadavky, odpovědi: celá historie se při každém požadavku restartuje.
3. Jak použít stávající kód OpenAI s Grok?
Odpověď: Změnou base_url na https://api.x.ai/v1 a API klíče – kompatibilita formátu zajistí zbytek, včetně OpenAI SDK a Vercel AI SDK.
4. Co čteš v odpovědi a využití?
Odpověď: choices nese odpovědi s finish_reason; usage detailizuje tokeny, včetně reasoning_tokens pro modely uvažování – základ pro sledování nákladů.
5. Jak čistě migrovat na Responses API?
Odpověď: Postupně: nový vývoj v Responses, stávající koncové body převáděny jeden po druhém s opětovným testováním promptů – srovnání obou formátů guiduje konverzi.
Pochopte zastaralé, budujte pro moderní: plán postupné migrace v tomto kurzu je vaší mapou – bez velkého třesku.