MaaS User Guide
This guide explains how developers and application users call models through Model as a Service (MaaS). You will learn how to create an API key, find the published models available to you, send an OpenAI-compatible request, and review your own quota and usage.
For the product overview, see Model as a Service (MaaS). For administration tasks, see MaaS Administrator Guide.
TOC
Open My SubscriptionsFind your models and endpointCreate an API keyCall a modelStreaming responses and completion checkUnderstand quota behaviorView personal usageUnderstand request errorsSecurity recommendationsOpen My Subscriptions
- Open the account menu in the top-right corner of the Alauda AI Platform console.
- Select My Subscriptions.
MaaS opens in a side panel over the current page. It is tied to your user identity rather than to a project namespace, so you can open it from any view. In 2.9, the available model name is the published model's client-facing name, which can be different from the underlying Kubernetes service name or provider model name.
The panel contains two tabs:
- API Keys — create and manage your MaaS credentials and find an access example.
- Usage — review quota status and personal usage for a subscription.
Find your models and endpoint
On the API Keys tab, the Access section lists the models currently available to you. Each row shows the model name and endpoint.
Select a model to update the example request. Use the copy control next to the endpoint or example request to copy it to your clipboard.
The endpoint normally has this form:
Use the published model name shown in the access list as the model value in your request. This is the clientModelName configured by the administrator. Do not use the name of an underlying Kubernetes resource or provider deployment unless the administrator intentionally used that same name as the client model name.
Create an API key
- On the API Keys tab, click Create API Key.
- Enter a descriptive key name, such as
my-chatbot-dev. - Select the subscription to use.
- Select a validity period. Depending on the platform policy, you can choose a preset such as 30 or 90 days, a custom duration, or a permanent key.
- Click Create.
- Copy the plaintext key and store it securely.
The plaintext key is shown only once and cannot be retrieved later. The dialog also provides a ready-to-run request with the new key filled in. Treat the key like a password:
- Do not commit it to source control.
- Do not include it in browser code or public notebooks.
- Store it in a secret manager or an environment variable.
- Create separate keys for separate applications when possible.
- Revoke a key immediately if it may have been exposed.
The key list shows the key name, status, subscription, creation time, and last-used time. A key can have one of the following statuses:
active— can be used to call subscribed models.expired— its validity period has ended.revoked— it has been disabled and cannot be used.
You can Revoke an active key. After it is revoked, you can delete it from the list.
Call a model
MaaS exposes an OpenAI-compatible API. Set the gateway URL and API key as environment variables:
Send a chat completion request with curl:
You can also use an OpenAI-compatible Python client:
Replace <published-model-name> with the client-facing model name shown in your Access list. The MaaS gateway selects an available upstream for that published model according to the administrator's priority and weight settings; your application does not need to know the backend service URL or provider model name.
Streaming responses and completion check
When you set "stream": true, MaaS returns the answer as a Server-Sent Events (SSE) stream of data: lines, ending with a data: [DONE] sentinel. If the stream is cut off midway — either because the upstream model stopped sending or because your client went away — the HTTP status is still 200, because the response headers were sent before anything was cut. The status code alone cannot tell you whether a stream finished.
Check completeness with the [DONE] sentinel: a complete stream ends with data: [DONE]; a truncated stream does not emit it.
With the OpenAI SDKs:
- Python / Node.js: iterate the stream to the end and inspect the last chunk. A complete stream's last chunk has
finish_reasonset to a terminal value such asstop,length, orcontent_filter; a value ofnullor a missing chunk means the stream did not end normally. - Add
stream_options={"include_usage": True}to your request. A complete stream's final chunk includes ausageblock; a truncated stream has no such chunk.
With curl, read every line until you see data: [DONE]. If the connection closes before that line arrives, the response is incomplete.
Example — streaming with Python, verifying completion:
A truncated stream may not include a final usage report. Do not infer token consumption or quota deductions from the HTTP status alone; check the platform usage and quota views.
If you need to retry on truncation, retry the whole request. There is no way to resume a partially delivered stream. A retry can cause the upstream to process the request again, so review the risk of duplicate work before retrying.
Understand quota behavior
MaaS quotas are configured by the administrator for each model in your subscription. A subscription can have multiple time windows, such as an hourly limit and a daily limit.
Quota consumption is tracked per user, subscription, and model. Your API keys share your user quota:
- Creating a second API key does not reset or increase your quota.
- Requests made with your different keys count toward the same user allowance.
- Other users have separate quota buckets.
When a quota window is close to its limit, reduce request volume or ask your administrator to review the subscription. When the quota is exhausted, the gateway returns 429 Too Many Requests. The quota panel shows the configured limit, current usage when available, and the reset time.
View personal usage
Open the Usage tab in My Subscriptions:
- Select a subscription.
- Review the per-model quota bars.
- Choose a time range: Last 24 hours, Last 7 days, or Last 30 days.
- Optionally filter the chart by model or API key.
- Click refresh to load the latest data.
The usage summary includes request count, total tokens, and cached tokens. The chart shows the token series over time, including uncached input, cached input, and output tokens when the backend provides those values.
This is a personal view: it includes only requests made with API keys that belong to you. It does not show another user's usage, even if you are an administrator in another part of the platform.
Understand request errors
A model can also be visible in the access list but temporarily unavailable while its inference service is not ready. If requests continue to fail after the service should be ready, contact the administrator with the model name and request time.
Security recommendations
- Keep API keys out of source code, Git repositories, shell history, and client-side applications.
- Use the shortest validity period that meets your needs.
- Use one key per application or environment so a compromised key can be revoked without interrupting unrelated applications.
- Revoke unused or exposed keys from My Subscriptions.
- Never share the MaaS API key with the external provider. MaaS handles the upstream provider credential on the gateway side.