API-headers och hantering av överskridanden
På denna sida
Bestäm vilka förfrågningar som använder din kapacitet
Att reservera kapacitet löser bara halva problemet: du måste fortfarande välja vilka förfrågningar som faktiskt drar nytta av den. Provisionerad genomströmning är inte ett engångsköp du gör i början av månaden; det är en mekanism du styr för varje anrop. xAI exponerar dedikerade HTTP-headers för detta ändamål som avgör, förfrågan för förfrågan, om trafiken ska gå via din dedikerade kapacitet eller den delade poolen. En fast allokering blir därmed en operativ hävstång som dina team manipulerar direkt från applikationskoden.
Frivilligt kringgå dedikerad kapacitet
Den första headern används för att exkludera en förfrågan från din allokering:
curl https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "x-pt-disable: true" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.3",
"messages": [{"role": "user", "content": "Summarize this document."}]
}'
Att avstå från sin egen kapacitet kan verka kontraintuitivt. Fyra situationer motiverar detta i den dagliga driften. För det första icke-kritiska uppgifter: en batchanalys som startas klockan 22.00 eller ett fördröjt bearbetningsjobb behöver ingen latensgaranti, och det vore synd om det förbrukade allokeringen som är betald för interaktiv trafik. För det andra bevarande av kapacitet vid toppbelastning: genom att inaktivera provisionerad genomströmning för sekundär bearbetning frigör du allokering exakt när prioriterade förfrågningar anländer i stora volymer. Headern används också för A/B-testning, när du vill mäta det faktiska prestandagapet mellan dedikerad och delad kapacitet baserat på din egen belastning snarare än på ett löfte från leverantören. Slutligen är den värdefull för felsökning: att tvinga förfrågan genom den delade poolen avslöjar omedelbart om den observerade anomalin härrör från den provisionerade kapaciteten eller från din kod.
Dirigera en förfrågan till en specifik pool
Den andra headern dirigerar anropet till en identifierad kapacitetspool:
curl https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "x-pt-id: pool-support-client" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.3",
"messages": [{"role": "user", "content": "How can I help you?"}]
}'
Denna header blir oumbärlig så snart flera applikationer inom din organisation anropar Grok. Du skapar då separata pooler – en pool-support för chattboten för kundsupport, en pool-analysis för dokumentanalys och en pool-internal för affärsverktyg – där var och en fungerar oberoende. Segmentering isolerar prestanda: en dokumentanalyskampanj som startas på en måndag morgon försämrar inte längre svarstiderna för supporten. Det genererar också en förbrukningsfördelning per användningsområde, vilket ger ett faktabaserat underlag för intern debitering eller prioritering, där du tidigare förlitade dig på gissningar. Dessutom förhindras det inneboende att en enskild applikation monopoliserar kapaciteten på bekostnad av andra.
Vad som händer vid överskridande
När trafiken överstiger den provisionerade kapaciteten sker återfallet automatiskt och tyst: förfrågan går till den delade poolen med betalning efter användning (pay-as-you-go), standardpriser för modellen tillämpas och den omfattas av de vanliga hastighetsbegränsningarna. Inget fel returneras; din applikation märker ingenting.
Denna diskretion har två sidor. När det gäller tillgängligheten är nyheten god: du kommer aldrig att stöta på ett 429-fel orsakat av att den provisionerade kapaciteten överskridits. När det gäller ekonomi och tjänstekvalitet är det mindre bra. Förfrågan debiteras enligt pay-as-you-go-taxan, som potentiellt är högre; svarstiderna kan variera eftersom bearbetningen sker på delad infrastruktur; och framför allt täcker SLA:n på 99,9 % endast förfrågningar som bearbetas inom den provisionerade genomströmningen. Ett överskridande bryter alltså ingenting, det får dig bara att glida tyst ut ur det omfång du betalar för. Management API exponerar andelen förfrågningar som bearbetats i provisionerat läge kontra pay-as-you-go: granska denna kvot varje månad precis som en faktura. En stigande överskridandegrad är signalen om att du behöver öka allokeringen.
Översätt prioritet till applikationskod
Istället för att multiplicera anropsfunktioner består den mest robusta metoden i att kvalificera prioritet vid själva anropet:
import httpx
def query_grok(prompt: str, priority: str = "normal"):
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
if priority == "low":
headers["x-pt-disable"] = "true"
elif priority == "high":
headers["x-pt-id"] = "pool-critical"
response = httpx.post(
"https://api.x.ai/v1/chat/completions",
headers=headers,
json={
"model": "grok-4.3",
"messages": [{"role": "user", "content": prompt}],
},
)
return response.json()
Parametern priority blir det enda beslut som exponeras för affärslogiken, och routningspolicyn förblir koncentrerad till en enda funktion som du kan utveckla utan att röra resten av koden. Granska din egen anropskod och sortera varje ingångspunkt i en av tre kategorier: övningen visar regelbundet att en god hälft av trafiken inte hade något behov av dedikerad kapacitet.
Viktiga punkter
- Headern
x-pt-disable: truekringgår provisionerad kapacitet för en förfrågan - Headern
x-pt-iddirigerar trafiken till en specifik kapacitetspool - Överskridanden faller automatiskt tillbaka till pay-as-you-go utan felmeddelanden
- Segmentering i pooler möjliggör isolering av prestanda och spårning av förbrukning per applikation
- Övervaka överskridandegraden för att justera din allokering vid behov