Zrozumienie formatu odpowiedzi
Na tej stronie
Anatomia odpowiedzi
Gdy wyślesz żądanie do POST /v1/responses, serwer xAI zwraca strukturalny obiekt JSON. Zrozumienie każdego pola w tym obiekcie jest kluczowe, aby poprawnie wykorzystać wyniki w swojej aplikacji.
Pełna struktura
Oto typowa odpowiedź:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "Le machine learning est une branche de l'IA...",
"annotations": []
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
}
Główne pola
id
Unikalny identyfikator odpowiedzi w formacie resp-xxx. Wykorzystasz go do:
- Łączenia rozmów za pomocą
previous_response_id - Pobrania zapisanej odpowiedzi poprzez
GET /v1/responses/{id} - Usunięcia odpowiedzi poprzez
DELETE /v1/responses/{id}
status
Status odpowiedzi:
| Status | Znaczenie |
|---|---|
completed | Odpowiedź wygenerowana pomyślnie |
failed | Błąd podczas generowania |
incomplete | Odpowiedź przerwana (limit tokenów, filtr treści) |
in_progress | Generowanie w toku (strumieniowanie) |
Zawsze sprawdzaj status przed użyciem treści odpowiedzi w swoim kodzie.
output
Tablica zawierająca elementy odpowiedzi. Każdy element posiada pole type:
message: Odpowiedź tekstowa od modelufunction_call: Wywołanie narzędzia zażądane przez model
Treść tekstowa znajduje się pod adresem output[0].content[0].text. Adnotacje (cytaty, linki) znajdują się w tablicy annotations tego samego obiektu.
usage
Informacje o zużyciu, szczegółowo opisane poniżej.
Zrozumienie obiektu usage
Obiekt usage jest kluczowy dla śledzenia Twoich kosztów:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Tokeny wejściowe i wyjściowe
input_tokens: Liczba tokenów w Twoim prompcie (oraz w historii, jeśli łączysz rozmowy)output_tokens: Całkowita liczba wygenerowanych tokenów, włączając w to rozumowanietotal_tokens: Suma obu wartości
Tokeny rozumowania
output_tokens_details.reasoning_tokens wskazuje, ile tokenów model zużył na swoje wewnętrzne rozumowanie. Tokeny te są rozliczane, ale nie są widoczne w odpowiedzi tekstowej.
W powyższym przykładzie, na 180 tokenów wyjściowych, 120 przeznaczono na rozumowanie, a tylko 60 stanowi widoczną odpowiedź. Jest to typowy współczynnik dla modeli rozumujących.
Koszt w nano-USD
cost_in_nano_usd podaje dokładny koszt żądania. Konwersja jest prosta:
Koszt w USD = cost_in_nano_usd / 1 000 000 000
Dla naszego przykładu: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 $).
Wykorzystanie narzędzi po stronie serwera
Gdy model korzysta z wbudowanych narzędzi, obiekt usage zawiera również:
{
"server_side_tool_usage_details": {
"web_search_calls": 2,
"code_interpreter_calls": 0,
"x_search_calls": 1,
"document_search_calls": 0,
"file_search_calls": 0,
"mcp_calls": 0
}
}
Pozwala to dokładnie ustalić, które narzędzia zostały wywołane i ile razy.
Ekstrakcja tekstu w Pythonie
Oto solidny wzorzec ekstrakcji treści tekstowej:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Sprawdź status
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Wyświetl zużycie
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Kluczowe wnioski
- Każda odpowiedź posiada unikalny
id, który można wykorzystać do łączenia wątków lub pobierania danych - Zawsze sprawdzaj
statusprzed użyciem treści - Tekst znajduje się pod adresem
output[0].content[0].text reasoning_tokenssą rozliczane, ale niewidoczne w odpowiedzi- Podzielenie
cost_in_nano_usdprzez miliard daje koszt w dolarach