Slimme routering

Als het model in je request niet beschikbaar is, geeft slimme routering je een antwoord van een vergelijkbaar alternatief in plaats van een foutmelding. Je app blijft werken tijdens een storing, zonder dat je code voor retries hoeft te schrijven. De automatische modus werkt voor chat- en afbeeldingsmodellen. Bij spraak wordt alleen van model gewisseld als je zelf alternatieven kiest, en bij video's gebeurt dat nooit.

Hoe het werkt

1. Elk request gaat eerst naar het model dat je hebt gevraagd. De meeste problemen worden hier al opgelost: als één route naar het model vastloopt of een fout geeft, wordt het request via een andere route opnieuw geprobeerd voordat je er iets van merkt.
2. Pas als het model zelf niet kan antwoorden (alle routes zijn mislukt of er is geen route beschikbaar), grijpt slimme routering in.
3. De alternatieven worden op volgorde geprobeerd, elk met hetzelfde automatische herstel, totdat er één antwoordt.
4. In het antwoord staat welk model heeft geantwoord (model in de body, x-zurelay-model en x-zurelay-routed-from in de headers). Je betaalt het tarief van dat model.

Elke route naar het gevraagde model komt aan de beurt voordat een alternatief wordt geprobeerd. Je krijgt dus pas een ander model als het jouwe echt niet kan antwoorden. Als alles snel is mislukt, krijgen het model en de alternatieven elk nog één poging voordat je een foutmelding ziet. Een model waarvan bekend is dat het niet beschikbaar is, wordt direct overgeslagen.

Inschakelen

Voor een sleutel kies je één van deze instellingen:

Per request

Een lijst met alternatieven

Geef models mee naast model: maximaal drie alternatieven die op volgorde worden geprobeerd als model niet beschikbaar is, ongeacht de instelling van de sleutel of de header. De lijst wordt nooit naar het model gestuurd. De OpenAI Python SDK stuurt deze mee via extra_body. Ook afbeeldings- en spraakrequests ondersteunen de lijst. Bij een afbeeldingsbewerking die je als formulier verstuurt, geef je deze mee als een models-veld (herhaald, of als één door komma's gescheiden lijst).

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
      {
        "role": "user",
        "content": "Summarize this ticket in one line: ..."
      }
    ],
    extra_body={
      "models": [
        "gpt-6.1-sol",
        "gpt-6-astra"
      ]
    },
)
print(response.choices[0].message.content)

De header

x-zurelay-fallback: off    # never reroute this request
x-zurelay-fallback: auto   # use the automatic alternatives (chat and image models)

Dit is de volgorde van prioriteit: eerst models van het request, dan de header, dan de instelling van de sleutel en tot slot de standaardinstelling van de werkruimte.

Welke alternatieven kunnen antwoorden

• Het zijn modellen van hetzelfde type. Een chatmodel krijgt chatmodellen als alternatief, een afbeeldingsmodel krijgt afbeeldingsmodellen en een spraakmodel krijgt spraakmodellen. Een regel voor elk ander model (*) kan meerdere typen bevatten; elk request gebruikt alleen modellen van het eigen type.
• Ze kunnen lezen wat je meestuurt. Een request met een PDF of video gaat alleen naar alternatieven die deze kunnen lezen. Kan geen enkel alternatief dat, dan krijg je de foutmelding in plaats van een antwoord dat je bestand negeert.
• De sleutel mag ze gebruiken. Alternatieven die niet tot de toegestane modellen van een sleutel behoren, worden overgeslagen.
• Ze ondersteunen het endpoint. Op /v1/messages zijn de alternatieven Claude-modellen.
• Het request zelf is in orde. Als het model het request heeft geweigerd (een ongeldige parameter, een te lange prompt, een prompt die het niet wil tekenen of tekst die het niet wil uitspreken), wordt het niet omgeleid: de alternatieven zouden het ook weigeren.

Afbeeldingen

In de automatische modus gaat een afbeeldingsrequest eerst naar dezelfde familie (GPT Image 2.5 Sunburst naar Flare, Nano Banana Pro naar Nano Banana 2.1), en alleen naar modellen die ongeveer even goed tekenen. Een automatisch alternatief kost nooit meer dan 1.5 keer de prijs van het gevraagde model voor het gevraagde formaat. Die limiet geldt niet voor je eigen regels of de models-lijst van een request. In beide gevallen geldt:

• Hetzelfde formaat en dezelfde verhouding. Nano Banana-modellen interpreteren size en aspect_ratio op dezelfde manier. GPT Image vervangt een Nano Banana-formaat alleen als beide dezelfde afbeelding kunnen maken: 1K vierkant (1024x1024), 1K 3:2 of 2:3, 2K vierkant, 4K 16:9 of 9:16. Nano Banana vervangt een GPT Image-pixelformaat alleen als het exact die pixelafmetingen kan maken (1024x1024, 2048x2048), of als je geen formaat hebt opgegeven.
• Je referentieafbeeldingen. Een alternatief moet minstens zoveel afbeeldingen ondersteunen als je hebt meegestuurd (Nano Banana 14, GPT Image 16).
• Je opties. Een transparante background gaat alleen naar GPT Image-modellen.
• Eén model per antwoord. Als n hoger is dan 1, komt elke afbeelding van hetzelfde model.

Spraak

Bij spraak wordt alleen van model gewisseld op basis van je eigen regels of de models-lijst van een verzoek, nooit in de automatische modus. Elk spraakmodel gebruikt dezelfde stemmen, dus een alternatief leest je tekst voor in de gevraagde voice, met je instructions. De headers voor invoer- en uitvoertokens zijn die van het model dat antwoordt.

Automatische alternatieven

Live uit de catalogus: de alternatieven waarop elk chat- en afbeeldingsmodel terugvalt in de automatische modus.

Goed om te weten

• Een alternatief kan meer of minder kosten dan het model dat je hebt aangevraagd. Je verzoeklog toont welk model heeft geantwoord en wat het heeft gekost.
• Streaming werkt hetzelfde: er wordt niets verstuurd totdat een model antwoordt, en de chunks vermelden dat model.
• Antwoorden op afbeeldings- en spraakverzoeken bevatten dezelfde headers x-zurelay-model en x-zurelay-routed-from, en bij afbeeldingen in je bibliotheek staat welk model ze heeft gemaakt.
• Video's worden niet omgeleid: een videotaak blijft bij het model dat je hebt aangevraagd en wordt opnieuw ingediend totdat de video klaar is of de taak mislukt (kosteloos).