Postupna migracija na Responses API
Na ovoj stranici
Ažurirano 3. studenog 2026.: Mapiranje parametara prethodno je ukazivalo da
max_tokenszadržava svoje ime u Responses API-ju; xAI-jeva tablica mijenja ga umax_output_tokens, a brojači korištenja također mijenjaju imena. Izvor: Usporedba s Chat Completions.
Zašto i kada migrirati
Chat Completions endpoint označen je kao zastarjeli (legacy). Nastavit će raditi, ali mu se neće dodavati nove značajke. Ako tvoja aplikacija treba alate na strani poslužitelja (web pretraživanje, izvršavanje koda), pohranu razgovora ili šifrirano rezoniranje, migracija na Responses API postaje nužna.
Dobra vijest: ova se migracija može obaviti postupno. Ne moraš sve prepisivati odjednom.
Korak 1: Identificiraj značajke koje koristiš
Prije migracije, napravi pregled onoga što tvoja aplikacija koristi s Chat Completions:
# Audit your existing code
# Look for these patterns:
# 1. Basic calls (simple text)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Function calling
client.chat.completions.create(..., tools=[...])
# 4. Vision (images)
# messages with content as array [text, image_url]
# 5. Generation parameters
# temperature, max_tokens, top_p, stop, seed
Osnovni pozivi i streaming najjednostavniji su za migraciju. Pozivanje funkcija zahtijeva prilagodbu formata. Vision (vid) radi na sličan način.
Korak 2: Migriraj osnovne pozive
Migracija jednostavnog poziva slijedi ovaj obrazac:
# BEFORE — 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
# AFTER — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Mapiranje polja
Glavne promjene su:
messagess ulogomsystem→instructions(namjenski parametar)messagess ulogomuser→input(jednostavni niz znakova)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, prema xAI-jevoj tablici mapiranja;temperaturezadržava svoje imeresponse.usage.prompt_tokensicompletion_tokens→input_tokensioutput_tokens(pojedinosti:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Korak 3: Migriraj višesmjerne razgovore
Ovdje Responses API pojednostavljuje stvari. Umjesto rekonstrukcije povijesti sa svakim zahtjevom, povezuješ ih putem ID-a:
# BEFORE — Chat Completions (manage history yourself)
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
# AFTER — Responses API (server manages history)
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
Kod je jednostavniji i više ne moraš ručno upravljati nizom poruka.
Korak 4: Iskoristi nove značajke
Nakon migracije možeš iskoristiti značajke ekskluzivne za Responses API:
Ugrađeno web pretraživanje
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# The response includes citations with source URLs
Pohrana odgovora
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Keeps for 30 days
)
# Retrieve later
stored = client.responses.retrieve(response.id)
Šifrirano rezoniranje
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# The encrypted reasoning can be reused in subsequent requests
Preporučena strategija migracije
Umjesto migracije svega odjednom, postupaj u koracima:
- Identificiraj pozive Chat Completions u svom kodu
- Klasificiraj ih po složenosti (osnovno → streaming → pozivanje funkcija)
- Prvo migriraj nove endpointe ili značajke (greenfield)
- Zatim migriraj najjednostavnije postojeće pozive
- Zadrži Chat Completions za integracije trećih strana koje to zahtijevaju (LangChain, itd.)
Privremena koegzistencija
Sasvim je prihvatljivo pokretati oba endpointa usporedno tijekom prijelaza:
# Wrapper that abstracts the endpoint used
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
Ovaj ti pristup omogućuje postupno prebacivanje testiranjem svake migracije pojedinačno.
Ključne točke
- Migracija može biti postupna: nema potrebe za prepisivanjem svega odjednom
- Glavne promjene:
messages→input/instructions,choices[0].message.content→output_text - Višesmjerni razgovori prelaze s niza poruka na jednostavni
previous_response_id - Responses API daje pristup ekskluzivnim značajkama (web_search, pohrana, šifrirano rezoniranje)
- Tijekom prijelaza pokreći oba endpointa usporedno i migriraj po redoslijedu složenosti
Provjeri svoje znanje
Zastarjeli API je razumljiv, a migracija pripremljena.
1. Što znači status zastarjelosti i bez stanja (stateless) za Chat Completions?
Odgovor: Endpoint ostaje podržan, ali se više ne razvija: budući da je bez stanja, zahtijeva ponovno slanje cijele povijesti sa svakim pozivom—Responses API je moderni put.
2. Koje uloge strukturiraju poruke?
Odgovor: system (i developer), user, assistant—okvir, zahtjevi, odgovori: cijela se povijest ponovno pokreće sa svakim zahtjevom.
3. Kako koristiš postojeći OpenAI kod s Grokom?
Odgovor: Promjenom base_url na https://api.x.ai/v1 i API ključa—kompatibilnost formata obavlja ostalo, uključujući OpenAI SDK i Vercel AI SDK.
4. Što čitaš u odgovoru i korištenju?
Odgovor: choices nosi odgovore s finish_reason; usage detaljizira tokene, uključujući reasoning_tokens za modele rezoniranja—temelj za praćenje troškova.
5. Kako čisto migrirati na Responses API?
Odgovor: Postupno: novi razvoj u Responses, postojeći endpointi se pretvaraju jedan po jedan uz ponovno testiranje promptova—usporedba dva formata vodi konverziju.
Razumijevanje zastarjelog, izgradnja za moderno: plan postupne migracije ovog tečaja tvoja je mapa puta—bez velikog praska.