# Gateway integration guide — model aliases update

Updated 30 October 2026. Backend GA00.0.19.158. These additions preserve existing client contracts.

## Stable model aliases and model_auto — GA00.0.19.158

When an application requests a stable alias such as txt_good_auto, the gateway resolves its published assignment before dispatch. The top-level model_auto response field identifies the concrete model selected for that request. Display this value beside generated content and retain it with request_id in diagnostic records. It is response metadata, not a request parameter or another AI-generated answer.

Administrators can update an alias centrally without requiring applications to change model version names. Each request keeps its resolved assignment throughout execution; later mapping changes affect subsequent requests. Generic txt_*_auto and img_*_auto aliases may use any supported provider. The openai-cheap, openai-good and openai-best aliases are restricted to OpenAI text models.

Use authenticated GET /v1/model-aliases or GET /v1/model-aliases/txt_good_auto to inspect current assignments. These configuration lookups invoke no provider inference and consume no provider tokens. Actual generation remains normally billed. A lookup is a snapshot: the generation response identifies that request’s selection. Unassigned aliases return a clear error before provider dispatch.

Parse model_auto as an optional string at the response root, including SSE JSON events. It identifies selection, not successful generation; still check HTTP status, error and result. Existing explicit-model requests and omitted-model defaults retain their current behavior and response format. Never require this field for legacy requests.

Aliases: openai-cheap, openai-good, openai-best; txt_cheap_auto, txt_good_auto, txt_best_auto; img_cheap_auto, img_good_auto, img_best_auto

Supported generation routes: POST /v1/chat, /v1/img2txt, /v1/txt2image, /v1/image2image, /v1/multi_image2image. Alias selection is optional; targets must support the requested operation. Video and TTS aliases are not part of this feature. All nine aliases are initially unassigned; an administrator must publish a mapping before generation. The word auto means centrally maintained mapping, not per-request AI selection. No automatic model promotion or measured quality ranking is enabled.

Request example (after Admin assignment):
POST /v1/chat
{"model":"txt_good_auto","messages":[{"role":"user","content":"Hello"}]}
Response excerpt (illustrative model ID; not a claim of a current assignment):
{"request_id":"req_example","model_auto":"<actual-model-id>","result":{"type":"text","model":"<actual-model-id>","message":{"role":"assistant","content":"Hello"}},"usage":{},"error":null}
Lookup example:
GET /v1/model-aliases/txt_good_auto
{"request_id":"req_example","result":{"alias":"txt_good_auto","provider":null,"model_auto":null,"mapping_version":0},"usage":null,"error":null}
Unassigned lookup returns model_auto:null (not a generation failure); generation through that alias returns HTTP 503. Unsupported modality/capability returns HTTP 400. Mapping versions may be greater than zero even when currently unassigned. Preserve existing token limits, provider capability checks and error handling; never retry a potentially billed request merely because a mapping changed.

### 简体中文：model_auto

当应用请求 txt_good_auto 等稳定别名时，网关会先解析管理员发布的映射，再处理请求。响应顶层的 model_auto 字段说明本次请求选定的实际模型。客户端可将它显示在生成内容旁，并与 request_id 一起保存，方便查询和排错。它属于响应元数据，不是请求参数，也不是由 AI 额外生成的答案。

管理员可以集中更新别名映射，应用无需逐一修改模型版本名称。每次请求都会保留开始时解析的映射，后续修改只影响新请求。通用 txt_*_auto 和 img_*_auto 别名可以使用任何已支持的供应商；openai-cheap、openai-good 和 openai-best 则仅限 OpenAI 文本模型。

通过已认证的 GET /v1/model-aliases 或 GET /v1/model-aliases/txt_good_auto 可查询当前映射。这些配置查询不会调用供应商推理，也不消耗供应商令牌；实际生成仍正常计费。查询结果只是当前快照，本次生成响应才说明该请求选定的模型。未指派的别名会在调用供应商前返回明确错误。

请将 model_auto 作为响应顶层的可选字符串解析，SSE 的 JSON 事件中也会包含它。该字段只代表模型选择，不代表生成成功，仍需检查 HTTP 状态、error 和 result。原有直接指定模型名称或省略模型的请求保持原有行为和响应格式，旧请求无需强制包含此字段。

### Entry points

Use https://api-gateway.wmazing.cloud as the primary base URL or https://hk-api.wmazing.cloud for the Hong Kong forwarding route. Both reach the same backend/account and use the same existing gateway key and /v1 routes. Switching entry points does not change provider execution location, model prices or account data. HK may provide a more suitable connection path; mainland carrier latency/reliability is not guaranteed or validated. Primary HTTP remains optional; HK HTTP redirects to HTTPS. Use HTTPS for browser integrations to avoid mixed content. Keep the base URL without /v1 and append each documented route.

## Existing integration reference

See /guide.html, /guide-android.html, /guide-ios.html, /guide-web.html and /guide-curl.html for authentication, text/image inputs, responses, streaming, limits, usage and asynchronous video recovery. The downloadable platform prompts on those pages include this model_auto contract. Generation requires Authorization: Bearer <gateway-key>; provider keys remain on the server. Do not place privileged keys in public web bundles.

## Complete platform integration prompts

- [android integration prompt](/integration-android-prompt.md)
- [ios integration prompt](/integration-ios-prompt.md)
- [web integration prompt](/integration-web-prompt.md)
- [curl integration prompt](/integration-curl-prompt.md)