Skip to content

Choose how a key's calls are translated

Purpose: an app written for one provider's SDK can call a model on another provider: the gateway translates each call both ways. Most apps want the gateway's usual translation. An app that relies on a provider's own options, such as a service tier, may want them carried over to the other provider wherever there's a near equivalent. You choose that on the key, so each app gets the behaviour it was built for, and every answer says which applied. In every edition.

Before you start

  • You're an organisation admin. Other people see a key's translation on its detail, but don't change it.
  • Know what the app relies on. Any SDK to any provider lists what's translated and what has no equivalent.

Steps: choose it on a key

  1. Open Keys and choose the key, or choose Issue a key for a new one.
  2. On an existing key, choose Edit.
  3. Under Translation between API formats, choose:
    • Standard: the gateway's usual translation. Every key starts here.
    • Keep what the other format can't say: where it can, the gateway carries over what the other API has no field for, instead of leaving it out.
  4. To let an app choose for a single call, tick Let apps choose the translation per call. It's off by default.
  5. Choose Save (or Issue key for a new key).

Changing a key's translation to Keep what the other format can't say and letting apps choose per call

Steps: let an app choose per call

With Let apps choose the translation per call ticked on its key, the app sends the x-vidai-translation header with default (Standard) or preserve (Keep what the other format can't say) on the calls that need it. The header is never sent to the provider. The developer guide has examples: Choose it for one call.

If the key doesn't allow it, the call still succeeds under the key's own choice, and the answer says the header was ignored (below).

Steps: see what was adapted on a call

  • In the answer: every answer from a provider carries x-vidai-translation-profile (default or preserve), the choice that applied. When translation changed something, or couldn't carry it, x-vidai-adapted names it in the app's own field names, for example seed,top_k. The call still succeeded. How it tells you lists the names.
  • In Request logs: with tamper evidence on Enterprise, a call's Configuration says the translation its key had when the call was made. What Enterprise includes depends on the features your licence includes.

Check it worked

  • The key's detail says it under Translation: "Standard", "Keeps what the other format can't say", or either with "apps may choose per call".
  • The change reaches the gateway like any other change to the key, and the audit log records it.
  • The app's next translated call answers with the new value in x-vidai-translation-profile.

Good to know

  • Only chat translates across providers (Chat Completions, Messages, generateContent). Other endpoints go to a provider of the same format, where nothing is translated and the choice has no effect.
  • Keep what the other format can't say can change what a call costs: a priority service tier is served at the other provider's priority price.
  • A call to a provider of the app's own format is sent as written, whatever the key's choice.