Documentation
BASIC USER GUIDE

Get started with ModelMix

Follow this illustrated guide from account creation to your first conversation. Each chapter explains where to go, what to do and how to check the result. No programming is needed for web chat.

  1. Create an accountEmail or phone
  2. Sign inConfirm your organization
  3. Verify identityPersonal or enterprise
  4. Check available creditWallet or active plan
  5. Start using modelsChat or connect an app
Getting started · Select a step to read its instructions

Have these ready

  • An email address or phone number that can receive verification codes.
  • Your identity document and a phone or computer with a camera. Enterprise applicants also need company registration details.
  • A payment method offered by the recharge page, if you need to add credit or buy a plan. Available sign-in and payment methods depend on your account region and the enabled services.

Registration creates your personal organization and a default workspace. The organization owns identity verification and the wallet; workspaces hold keys, files and project settings. Check the selected organization before verification or payment. Your IP suggests a region during registration; you may choose another region before creating the account. The region is fixed after registration. Mainland China uses CNY; all other regions use USD. Changing the website language does not change your region or currency. Read the concept guide →

Before a paid request, check wallet capacity or an active ModelMix plan's daily points. Plans and the wallet are separate: points reset at midnight in Shanghai, and wallet fallback when points run out is off by default. Read about plans and points →

01 / ACCOUNT

Create your account

Entry: Console sign-in page ↗

Option A · Email registration

  1. Switch to account creation

    Select Email, then Create account below the sign-in form.

  2. Verify your email

    Enter your email and select Send code. Read the six-digit code in your mailbox and enter it before the displayed expiry. Check spam if it does not arrive; use the newest code after resending.

  3. Set a password and create the account

    Use 15–256 characters and avoid common or leaked passwords. Read the User Agreement and Privacy Policy, actively check the agreement box, then select Create account. Your personal organization and default workspace are created automatically; names can be changed after sign-in.

Option B · Phone registration

  1. Choose Phone and request a code

    Select Phone and Sign in with a code. In CN, enter a mainland Chinese mobile number; in other regions, include the + country code. Select Send code and enter the six-digit SMS code.

  2. Sign in to create the account

    Read and agree to the User Agreement and Privacy Policy, then select Sign in securely. If registration is open, a new phone number creates an account automatically; an existing number signs into its existing account. No initial password is required. You can set one later in Account settings → Sign-in & security.

How to know it worked

You enter the console, or see a security setup prompt for your account. Follow any required authenticator setup, then continue to organization verification. Registration itself does not complete identity verification.

If registration is closed or codes are unavailable, contact platform support. International accounts may also see Google or GitHub when configured; use your original sign-in method for an existing account with the same email.

Next: sign in →
02 / SIGN IN

Sign in to the console

Entry: Console → Email or Phone ↗

  1. Choose your account's sign-in method

    For email, enter your email and password, or switch to Sign in with a code if available. For phone, use an SMS code, or switch to a password if you have set one. Select Sign in securely.

  2. Complete any MFA prompt

    If asked, enter the current code from your authenticator app or an unused recovery code. MFA is an additional check, separate from the email or SMS code. If your organization requires enrollment, follow the setup screen, save recovery codes privately and sign in again.

  3. Check organization and workspace

    Check the organization and workspace selector at the top of the console. Select the project you intend to use. Wallets belong to organizations; changing workspace within the same organization does not create another balance.

How to know it worked

Your console shows the intended organization and workspace. A verification notice may still appear until the organization is verified.

Forgot your password?

On Email or Phone password sign-in, select Forgot password? Use the email reset link or SMS reset flow, set a new 15–256-character password, then sign in again. An enabled MFA still requires an authenticator or recovery code. Password reset signs out previous sessions. A phone account without a password can sign in by SMS first and set one in Account settings → Sign-in & security.

Gateway key is an alternative for users who already have a key. It grants only the key's permissions; use your personal account for verification, recharge and account settings.

Next: verify identity →

Find your way around the console

The Overview guide offers two paths: Chat with AI and Build with the API. Web chat uses your signed-in account; connecting an application requires an inference key. Select the intended organization and workspace before changing settings or paying.

Default console navigation
GroupPages
HomeOverview
WorkbenchChat · Models · Files · Agents & collaboration · Drama studio · Creative studio
Key settingsAPI keys · BYOK · Routing · Presets · Guardrails · Tools & plugins · Management keys
Subscriptions & balanceProduct subscriptions · Recharge orders · Cost overview
My accountAccount settings · Session management · Notifications · Support center · Privacy · Connection settings
Usage & recordsActivity · Usage insights · Exports · Usage charges · Refund records · Invoices · Funds ledger
Team & workspaceWorkspace management · Workspace members · Organization management · Service accounts · Billing permissions · Workspace budget · Audit history
Open the console →

Key settings, Usage & records and Team & workspace are collapsed initially; expand them to find API keys, request history or organization management. Available pages follow your permissions and available features. A hidden page is not necessarily a removed feature.

Account settings contains Profile & preferences, Sign-in & security, and Connection & privacy. Active sessions, recent security events and signing out other devices are in the separate Session management page.

03 / IDENTITY

Complete identity verification

Entry: Organization management → Identity verification ↗

Organizations in all regions must be verified before new recharges and model use. Verification belongs to the selected organization and is shared by its members and workspaces. If you cannot submit, ask the organization owner to complete it.

  1. Select the correct organization and type

    Choose Personal verification or Enterprise verification. In CN, personal verification uses your legal name and national ID; enterprise verification also needs the company name, unified social credit code and the legal representative's identity. The legal representative must complete the face check. International personal verification uses a passport; enterprise registration and representative authority require manual review after eKYC.

  2. Choose a verification device

    On a computer, choose Verify with your phone and Generate verification QR code. Scan it with your phone camera, fill in details and authorize verification on the phone; no additional sign-in is needed. Keep the computer page open. Alternatively choose Use this device's camera. On a phone, use the current device and allow camera access.

  3. Authorize and finish the provider check

    Read the authorization, confirm consent and select Start verification on the device being used. Follow the Alibaba Cloud identity and face checks. Only the person being verified should use the link; if the camera fails, open it in Safari or Chrome and allow camera access.

  4. Return and check the result

    After the provider flow, return to ModelMix. The computer page synchronizes the result; use Refresh verification status if needed. A browser redirect alone does not mean approval. If manual review is shown, retain the verification reference and contact support.

ComputerChoose type → Generate QR
Your phoneScan → Details → Face check
ModelMixRefresh → Verified or review
Phone verification flow · This is a process diagram
Verification status and next action
StatusWhat to do
Not verifiedSelect a type and start verification.
Starting / In progressContinue the current application and refresh its status. Avoid creating duplicates.
Manual reviewContact support with the verification reference and follow the request for evidence.
VerifiedThe current organization can proceed to recharge and model use, subject to balance and permissions.
Rejected / Expired / RevokedRead the result, correct the issue and apply again. Revocation also blocks new use by existing keys.
How to know it worked

The intended organization's status reads Verified. If the service is unavailable or not configured, contact platform support; retrying cannot complete an unavailable service.

Next: add credit →
04 / WALLET

Recharge and confirm credit

Entry: Recharge orders → Recharge ↗

Use a personal account with organization owner or Billing Admin permission, and complete the organization's verification first. Billing Viewer can view records. If the recharge button is absent, ask the organization owner to check financial permissions.

Recharging adds wallet funds; it does not purchase or renew a subscription. If an active plan already covers your usage, check its remaining points and wallet fallback before deciding whether to recharge. Plans and daily points →

  1. Check which wallet you are funding

    Check the organization shown on the finance page. Select Recharge, enter the desired credit amount in the displayed currency and stay within the page's allowed range.

  2. Preview the amount and fees

    Select Preview order to create an unpaid order from the current quote. Review spendable credits, platform fee and total payable before opening checkout. If the quote expires, preview again. Use the current page's quote for fees and limits.

  3. Choose a payment method

    Select one of the listed methods and choose Open or resume checkout. Depending on the method, scan the QR code, open the secure checkout link or continue to the online gateway. Only configured regional methods appear; an empty list means no method is currently available.

  4. Complete payment and confirm credit

    Pay before the displayed deadline, return to the original order and select Refresh payment status or Refresh records. Check that it is paid and the organization's balance or funds ledger includes the credit. Opening checkout or returning from it alone does not confirm payment.

  5. Recover a payment that is still pending

    Open the original order's details and choose Query original payment if offered, then refresh. If it remains processing or requires review, contact support with the order ID, payment time and channel transaction reference. Avoid paying a new order for the same unconfirmed transaction.

Spendable credits + Platform fee = Total payable

Recharge amount diagram · Only spendable credits enter the wallet
How to know it worked

The order shows Paid and its credit is visible in the intended organization's wallet records. Setting a key budget does not add money to this wallet.

How do I request a refund?

Open a paid order's details and select Request refund, or use the refund records page. Select an eligible order, enter the amount within Currently refundable, add a reason and submit. Unused refundable principal is held while the request is reviewed. Submission or approval does not mean the refund has reached your payment account; check its final status. Standard unused-principal refunds exclude fees and gift credit.

Next: use your first model →
05 / FIRST USE

Start a conversation or connect an app

Use web chat

  1. Open Chat and choose a model

    Open Chat, confirm the workspace and select an available model. Web chat uses your signed-in account; you do not need to paste an API key into the chat interface. Open the console ↗

  2. Send a short test message

    Try: Introduce yourself in one sentence. Wait for the response. Model requests can incur charges; check the selected model's price before sending.

  3. Check request and spending records

    Open Request activity to inspect the result, then Usage charges for the current workspace. A completed response can still have pending billing; refresh for the final settled charge. The organization's wallet is shared by its workspaces.

Connect an application with an API key

  1. Create a key in the intended workspace

    Open API Keys → Create key. For personal testing, choose a personal inference key; set its name, budget, expiry and any model restrictions. A budget is a spending limit, not a recharge. Open API Keys ↗

  2. Save the key and configure the application

    The full key is shown only when created or rotated. Save it privately; if lost, rotate it. Use the ModelMix base URL, an mmk- inference key and the exact model ID from the current catalog. A management key (urm-) cannot call models.

WorkBuddy / Coze configuration → · SDK quickstart → · AI assistant → · Creative Studio →

How to know it worked

A response appears in chat or your app and the request is visible in the intended workspace. If a key cannot use a model, check its permissions, verification, balance and budget in the FAQ below.

06 / ACCOUNT SECURITY

Manage password, MFA and sessions

Entry: Account settings → Sign-in & security ↗

Sessions and security events: Session management ↗

  1. Set or change your password

    Phone accounts without a password can request a new SMS code in the password setup form and set a 15–256-character password. To change an existing password, enter the current password, new password and confirmation; provide MFA if requested. A successful set, change or reset ends previous sessions, so sign in again.

  2. Enable an authenticator and save recovery codes

    Follow the MFA setup form: scan the enrollment QR with an authenticator app, enter its current code and save the recovery codes privately. Each recovery code can be used once. If prompted to set a password first, finish that step and sign in again before enrollment.

  3. Review sessions and sign out

    Open Session management to review active sessions and recent security events. Revoke sessions you do not recognize, or sign out other sessions. Use the console's Sign out action when leaving a shared device. If an API key leaks, rotate or disable it separately in API Keys.

How to know it worked

Account settings and Session management show the expected MFA and session status, and you have stored recovery codes privately. Never include passwords, codes, full API keys or identity documents in public screenshots or tickets.

07 / HELP

Common issues and support

Why can I sign in but not recharge or use models?

Check the current organization's identity status. Sign-in verifies your account contact, while identity verification approves the organization. If a mandatory MFA setup is shown, complete that too. A verified organization still needs sufficient funds, budget and model permissions.

I have not received a verification code.

Check the email address or phone country code, spam folder and the displayed resend countdown. Request a new code after the countdown and use the latest one within its displayed expiry. If codes are unavailable or rate limited, follow the retry time or contact support.

The verification camera or QR code does not work.

Allow camera access and use Safari or Chrome. A computer without a camera can use Phone verification. Generate a new QR if the link expires and use the phone's own flow; do not copy a computer provider link onto another device. Only the person being verified should open the link.

The payment provider says paid, but my wallet has not changed.

Check the original order under the intended organization. Refresh or query the original payment, and retain the order and channel reference. Processing and review states require further confirmation; contact support if unresolved and avoid duplicate payment.

Why is my spendable balance different, or a request still blocked?

Available capacity also accounts for running requests, pending settlement and holds. Keys and workspaces can have separate budgets, expiry and model restrictions. Subscribers should check remaining points, plan status and wallet fallback; recharging does not renew a plan or raise key budgets. Page language does not change wallet currency.

My app reports 401, 402, 403, 404 or 429.

401: check the key and base URL. 402: inspect wallet capacity, budgets and, for subscribers, plan status, remaining points and wallet fallback. 403: inspect identity verification and permissions. 404: check the path and exact model ID. 429: reduce request frequency or concurrency and follow the returned retry guidance. Use the actual error message to identify the cause.

Why did my old sessions sign out?

Password set, change and reset revoke prior sessions. Sign in again with the updated credentials and MFA if enabled. API keys have their own lifecycle; inspect them separately if needed.

Submit a support request

Entry: Support center → Submit a question ↗

Confirm the current organization, choose an issue category, describe what happened and add the related request, order or refund ID when available. Include the time with timezone and the displayed error. If support needs screenshots, send redacted copies through its designated channel. Track replies in the same ticket. If you cannot sign in, use the support contact provided by ModelMix.

Keep passwords, verification and recovery codes, full keys and identity documents out of the ticket. For identity evidence, follow the support team's designated restricted submission process.

GET STARTED

Build on every model
with one interface.

AIDMX is an OpenAI-compatible gateway with provider-aware routing, automatic fallbacks, usage controls and asynchronous wallet settlement. Configure your application with a AIDMX base URL and inference key, then check the selected model and endpoint capabilities.

Base URLhttps://stg-api.aidmx.net/v1

The OpenAI-compatible base URL ends in /v1; use /models on that same base URL for discovery. Do not use /api/v1 or append /chat/completions to a client's base URL. /api/v1 serves accounts, workspaces and console features. Model calls need an mmk- inference key, not your website password or a management key.

Choose the API for your client
ClientBase URLRequest path
OpenAI SDKhttps://stg-api.aidmx.net/v1/chat/completions · /responses
Anthropic SDKhttps://stg-api.aidmx.net/v1/messages
Google Gen AI SDKhttps://stg-api.aidmx.net/v1beta/models/…:generateContent

Set the Google Gen AI SDK API version to v1beta. Use the full ModelMix catalog ID for every protocol. Check model details for supported protocols, tools and input types.

Install an SDK

bash
pip install openai

Sign into the console, verify your organization, check its wallet balance or active plan allowance, and create a workspace inference key. The organization and workspace determine the account region and available models; the page language does not change them. Query /v1/models?task_type=chat&available_only=true with that key and choose a priced chat model that has not retired. Catalog configuration does not guarantee live provider availability.

New here? Understand users, organizations, workspaces and keys →

Send your first request

python
from openai import OpenAI

client = OpenAI(
    base_url="https://stg-api.aidmx.net/v1",
    api_key="mmk-...",
)

catalog = [item.model_dump() for item in client.models.list().data]
chat_models = [
    item["id"] for item in catalog
    if item.get("task_type") == "chat"
    and item.get("pricing_configured")
    and item.get("lifecycle", {}).get("state") != "retired"
]
if not chat_models:
    raise RuntimeError("No priced chat model is available for this key.")

response = client.chat.completions.create(
    model=chat_models[0],
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
)

print(response.choices[0].message.content)
FEATURES & CONCEPTS

Features & concepts

Understand who uses ModelMix, where resources belong, which key an application needs and how spending is controlled.

Example: a team's support applicationYou sign in as a user and join your company's organization. Its Testing and Production workspaces keep separate keys, files and configurations while sharing the organization's wallet. Give the application a key from the intended workspace. To use your own provider account, configure BYOK credentials in that same workspace.

People and resource ownership

User / account

Your personal sign-in identity, with your profile, security settings and login sessions. A user can join multiple organizations and workspaces, with access determined by membership and role in each one.

Organization

The owner of team resources and billing. An organization contains workspaces and has a shared wallet, identity verification and billing currency. Personal registration creates a personal organization and a default workspace, so individual developers use the same structure as teams.

Workspace

A project or environment within one organization, such as testing or production. Each workspace manages its own API keys, BYOK credentials, files, presets and policies. Workspaces in the same organization share its wallet and can have separate spending budgets.

Member / role

Membership grants a user access to an organization or workspace. Roles determine what they can manage: organization owners and administrators handle organization governance, while workspace administrators manage their workspace. Financial permissions are granted separately; workspace access alone does not grant access to organization finances.

Keys and application identities

API key / inference key

A ModelMix credential for calling models from an SDK or application, created in API Keys. Inference keys use the mmk- prefix and belong to a workspace. They can restrict models, providers, spending, request rates and expiry. Use this key in your application's api_key setting.

Personal key

An inference key tied to a person and their current workspace membership. It suits individual development and debugging. Leaving the workspace or disabling the personal account blocks further use.

BYOK — Bring Your Own Key

Bring Your Own Key means configuring your own model-provider credential in a workspace. Your application still sends a ModelMix inference key; the gateway uses the configured provider credential for eligible requests. The provider bills your account directly, and ModelMix may charge a service fee under the regional BYOK policy. If a permitted fallback uses platform credentials, platform inference billing applies.

Service account / service key

A service account is an application identity owned by an organization and authorized for specific workspaces. Its service keys are inference keys for servers and scheduled jobs. Administrators manage the account and grants; the creator's personal login is not the application's authentication identity.

Management key

A credential for automating authorized management operations in one workspace, using the urm- prefix. Explicit scopes can cover inference keys, BYOK credentials, guardrails and reports. It cannot call models, operate the wallet or manage other workspaces. Read and write permissions are granted separately.

Balance and spending controls

Wallet / balance

The organization's funds for platform inference and applicable service fees. Capacity for new requests deducts in-flight admission amounts, pending charges and other held funds. A positive low balance can admit one final request when the organization has no other in-flight requests; actual settlement may make the balance negative. Paid requests stop when the balance after pending charges is nonpositive. Recharging repays outstanding usage and restores capacity. The wallet currency follows the organization's billing configuration.

Budget / key limit

A spending limit for a workspace or key, optionally set for a day, week, month or lifetime. Setting a budget does not add wallet funds. Each applicable key, workspace, guardrail and Agent inference budget counts actual charges, in-flight admission amounts and pending costs. Positive remaining capacity below one admission amount allows one final request only when that scope has no other paid requests running. Its actual charge can exceed the budget; exhausted budgets block new paid calls. BYOK usage can also count toward a key limit when enabled.

In-flight usage / settlement

Running requests occupy part of the available wallet and budget capacity. After generation, charges are calculated from actual usage and can remain pending briefly. Query the original request for its settled final charge; receiving an answer does not mean billing and usage reports have finished updating.

Models and request behavior

Model

The capability your application requests, identified by the model field, such as author/model. Models support different tasks, parameters, context sizes and prices. Check the current workspace key's model catalog before choosing one.

Provider / endpoint

A provider supplies model services; an endpoint is a specific configured route to that service. One model may have multiple providers or endpoints with different capabilities, availability and privacy declarations. A catalog entry describes configuration; live availability depends on the provider.

Routing / fallback

Routing selects an eligible endpoint for a request; automatic model routing can also select a model. Fallback tries an eligible alternative when the initial route fails. These choices still obey model access, budget and privacy policies.

Preset

A saved, reusable request configuration, such as a model, parameters and routing preferences. Presets help applications use consistent settings; using a preset still requires a valid inference key and access to its selected models.

Guardrails

Policies that constrain requests, including model or provider access, sensitive content and shared spending limits. Organization policies can apply to workspace members and keys; a request must satisfy all applicable policies.

Privacy / ZDR

Privacy policies control eligible data-handling routes and logging. ZDR means Zero Data Retention and filters for endpoints declaring the required provider retention policy. Explicitly saved chats, files and billing records follow their own retention rules; account region alone does not guarantee a physical data location.

Continue with the detailed guides: API key authentication · Billing and BYOK · Provider routing · Guardrails · Privacy

COMMON TOOL CONFIGURATION

Connect your everyday tools to ModelMix

Prepare your API base URL, inference key and model ID, then follow the guide for your tool. Use the flow and field reference alongside the steps.

01Prepare in consoleInference key + model ID
02Configure your toolBase URL + key + model
03Select and verifyNew chat + usage check
Connection flow
  1. Create a dedicated inference key

    After verifying your organization and checking wallet capacity or active plan points, use API keys → Create key to issue an ordinary mmk- inference key. Name it after your tool, such as WorkBuddy, and set a budget. All tools use the same creation flow. Management keys (urm-) and website credentials cannot run inference. Open API keys →

  2. Check the URL and available models

    Use the base URL below and query models with the same key. Copy a priced, non-retired chat model id. For agent tasks, check tool-calling support on its endpoint. Replace MODEL_ID_FROM_CATALOG in these examples.

Base URLhttps://stg-api.aidmx.net/v1
bash
export MODELMIX_API_BASE="https://stg-api.aidmx.net/v1"
# Set MODELMIX_API_KEY locally to your inference key, then query models:
curl --fail-with-body "$MODELMIX_API_BASE/models?task_type=chat&available_only=true" \
  -H "Authorization: Bearer $MODELMIX_API_KEY"

The API base URL ends in /v1; use the address shown here. Coze cloud requests need a publicly reachable HTTPS service. localhost, 127.0.0.1 and private addresses only work in environments that can reach them. Saving a key in a third-party tool authorizes calls with that key; enter it only in credential settings.

These examples apply to tool versions supporting a custom OpenAI chat endpoint. Menu names and access depend on the tool's current interface.

WORKBUDDY

WorkBuddy configuration

Connect through a custom provider using the fields below.

Create an ordinary inference key in ModelMix under API keys → Create key; no special key type is needed. For an existing key, More actions → Connect WorkBuddy can verify it and copy fields or download a setup guide. This does not modify the WorkBuddy client. Existing key secrets cannot be retrieved; use the secret saved when you created the key.

Field reference (replace placeholders)
FieldValueNotes
Display nameModelMixA label of your choice
ProviderCustom / 自定义Use the OpenAI-compatible chat endpoint
Base URL / 接口地址https://stg-api.aidmx.net/v1Keep /v1; do not append /chat/completions
API Keymmk-…Your inference key, without a Bearer prefix
Model ID / model nameMODEL_ID_FROM_CATALOGReplace with the exact id returned by /models for your key
  1. Open model settings

    Open Settings → Model, add a custom model and select Custom as the provider.

  2. Enter fields and save

    Enter the base URL, mmk- inference key and exact model ID. Keep Custom Protocol off so WorkBuddy appends /chat/completions. Set tool, image and reasoning options to match your endpoint.

  3. Select the model in chat

    Save, then select the new model in the conversation’s model picker and send a test message.

Check that it works

Start a new conversation, select your ModelMix model explicitly and send “Reply only: Connected”. After a reply, check the model and request in ModelMix Activity; billing may settle later. For file tasks, then verify tool calling with a disposable test file.

Official reference: WorkBuddy model configuration ↗

COZE / WEB

Coze web configuration

In a coze.cn Agent’s model menu, choose Add custom model → Custom connection and use the fields below. Current documentation requires a personal Advanced plan or higher; enterprise access and Agent type also affect availability.

Field reference (replace placeholders)
FieldValueNotes
Display nameModelMixA label of your choice
Model protocolChat APIUse the OpenAI-compatible chat endpoint
API URLhttps://stg-api.aidmx.net/v1Keep /v1; do not append /chat/completions
API Keymmk-…Your inference key, without a Bearer prefix
Model ID / model nameMODEL_ID_FROM_CATALOGReplace with the exact id returned by /models for your key
  1. Choose custom connection

    Sign in to Coze web, open your Agent’s conversation and model menu, then add a custom model using Custom connection.

  2. Add and select the model

    Use ModelMix as a display name and the exact catalog id as the model ID. Choose Chat API and enter the URL and key above. Keep input/output limits within your ModelMix endpoint’s limits and enable image input only if supported. Add it and select it for the current Agent.

Check that it works

Start a new conversation, select your ModelMix model explicitly and send “Reply only: Connected”. After a reply, check the model and request in ModelMix Activity; billing may settle later. For file tasks, then verify tool calling with a disposable test file.

Use in a Coze Studio workflow

Low-code model integration at code.coze.cn has separate enterprise access. Eligible administrators use Enterprise organization management → Model access → Custom models, configure the same URL, model ID and Authorization credential, then grant workspace access. Where available, an HTTP workflow node can call the full /chat/completions URL with Authorization: Bearer plus your inference key; that node does not replace the Agent’s default model.

Coze Studio: custom model integration ↗ · Video plugin guide →

Official reference: Coze model settings ↗

COZE / DESKTOP

Coze desktop configuration

This guide covers the macOS / Windows desktop app. Use the same three connection parameters as on the web and select Chat API.

API URLhttps://stg-api.aidmx.net/v1
  1. Sign in and find the model menu

    Install the official desktop app and sign in. Open your Agent’s conversation, expand its model list and add a custom model.

  2. Save the ModelMix connection

    Choose Custom connection and enter a display name, exact model ID, Chat API, the URL above and your mmk- key. Match capabilities and length limits to your endpoint. View the full field table →

  3. Switch and verify

    Select the added model in the conversation. If the entry is missing, check app version, plan and Agent type, and compare with the web UI. Mobile apps currently do not support adding or managing custom models.

Check that it works

Start a new conversation, select your ModelMix model explicitly and send “Reply only: Connected”. After a reply, check the model and request in ModelMix Activity; billing may settle later. For file tasks, then verify tool calling with a disposable test file.

Official reference: Coze model settings (web and desktop) ↗

TROUBLESHOOTING

Troubleshoot your connection

Common issues and checks
IssueCheck
401 / Authentication failedUse an active, unexpired mmk- inference key. Paste only the key in a client’s API Key field; manual HTTP headers require Authorization: Bearer mmk-….
402 / Insufficient capacityCheck wallet capacity, key budgets and billing status. Subscribers should also check plan activation, remaining points and wallet fallback. Recharging does not renew a plan.
403 / Access deniedCheck organization verification, model allowlists and region restrictions. A missing Coze entry also depends on its plan, Agent type and enterprise permissions.
404 / URL or model not foundKeep /v1 in the base URL and avoid duplicating /chat/completions. Use the exact model ID returned for the same key.
429 / Too many requestsReduce concurrency, respect Retry-After and check key/provider limits. Avoid simultaneous automatic retries across tools.
Chat works, tools or images failCheck endpoint tool/image capabilities, client options and request parameters. A text reply does not verify all agent capabilities.
Timeout or no streaming outputRun the SSE test below, then check proxy buffering of text/event-stream, connectivity and provider status. Coze cloud cannot reach your localhost.

Verify streaming

Set MODELMIX_API_BASE and MODELMIX_API_KEY locally, replace the model placeholder below, then run. This makes one billable inference request. A successful stream emits data: events and ends with [DONE].

bash
curl --fail-with-body -N "$MODELMIX_API_BASE/chat/completions" \
  -H "Authorization: Bearer $MODELMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_CATALOG","messages":[{"role":"user","content":"Reply only: Connected"}],"stream":true,"max_tokens":256}'

If issues persist, record the time, tool version, model ID, HTTP status and request ID from the response for support. Mask keys in screenshots, logs and recordings. Update the tool after rotating or disabling its dedicated key.

The catalogue shows planned retirement dates, public notices and suggested replacements. After publication, the deadline stops new requests, including automatic routing and response-cache hits; previously submitted tasks remain recoverable. Requests are never redirected to a suggested replacement automatically. Verify its capabilities, price and permissions before changing configuration.

MODEL DISCOVERY

Model details, comparison and estimates

The public catalog provides model details, comparisons of up to four models and collections based on task and capability declarations. Share filters and model selections through page URLs. Console details and comparisons use your connected gateway.

The public catalog shows models, capabilities and prices available in your region. supported_parameters summarizes model parameters; check each endpoint's parameter_contract for its specific support. Joint filters require the same endpoint to satisfy parameters, provider, ZDR and context. Catalog listings do not guarantee live provider availability.

Estimates use the current region's published model sale price for one request, including request fees, cache, audio, images and long-context tiers. Read the returned currency, which can be USD or CNY; do not directly compare or add different currencies. Wallet settlement may require conversion. Media uses character, second or resolution rates; rerank uses tokens or search units. Cache and audio tokens are included in total input tokens; units for other tasks are ignored by that endpoint. BYOK, tools, taxes, retries and account policies are excluded.

Disabled, unpriced or over-limit endpoints return no cost. Token-billed video has unpredictable usage and cannot be estimated; configured free endpoints explicitly show zero. The catalog snapshot identifies the compared configuration without reserving prices. Collections are not quality rankings; measured leaderboards are not provided. Saved custom collections are available in the console model catalog.

HTTP
GET /v1/models/author/model
GET /api/v1/model-discovery/collections
POST /api/v1/model-discovery/compare
Content-Type: application/json

{"models":["author/model"],"workload":{"prompt_tokens":1000,"completion_tokens":200,"cached_prompt_tokens":100}}
MODEL COLLECTIONS

Save and share model collections

Saved collections in the console model catalog contain a name, description, ordered model list and per-model notes. Add catalog models in bulk, import favorites, reorder, compare or try selected models. A personal account session and active workspace are required; inference and management keys cannot access collections.

Private collections are visible only to their creator, including when another reader is a workspace administrator. Shared collections are visible to workspace members and maintained by administrators. Only the creator, while still an administrator, can change visibility. Members can keep private copies independently of the source being withdrawn or deleted. There is no anonymous or cross-workspace sharing.

Each user can keep 50 private collections per workspace; a workspace can hold 50 shared collections, with 100 distinct models per collection. Limits are 80 characters for names, 1,000 for descriptions, 500 per note and 128 KiB per collection. API updates, copies and deletes require the current expected_revision; refresh and review after a version conflict.

New entries must exist in the current regional catalog. Retired entries remain visible with an unavailable marker and can still be annotated, removed or copied. Removed retired entries cannot be re-added. Collections grant no inference permissions and do not trigger paid requests. After a save timeout, refresh and check before retrying; on a revision conflict, your draft remains available until you reload and edit again.

HTTP
POST /api/v1/workspaces/{workspace_id}/model-collections
Authorization: Bearer urs-your-session
X-ModelMix-Workspace: ws-your-workspace
Content-Type: application/json

{"visibility":"private","document":{"name":"Research","description":"","items":[{"model_id":"author/model","note":"Candidate"}]}}

PUT /api/v1/workspaces/{workspace_id}/model-collections/mcol-returned-id
{"expected_revision":1,"visibility":"workspace","document":{"name":"Research","description":"","items":[]}}

POST /api/v1/workspaces/{workspace_id}/model-collections/mcol-returned-id/copy
{"expected_revision":2,"name":"My copy"}

DELETE /api/v1/workspaces/{workspace_id}/model-collections/mcol-returned-id?expected_revision=2

Review and migrate model references

Workspace administrators can preview exact references in presets, enabled key allowlists, shared collections and their own private collections. Review and select up to 100 resources for replacement. Previews last ten minutes and are bound to your personal session and workspace. Changed resources or catalogues require a new preview; recover a lost response by checking the receipt or retrying the same operation without duplicate changes.

Presets gain a restorable version and collection notes are preserved. Collections already containing the target require manual editing. Wildcards, aliases, other users' private data, saved chats and external applications require separate review. Check replacement prices, capabilities and privacy, then test your application. Retired collection entries keep their notes and disable inference. Exact references in eligible presets and keys predating an event also qualify for model retirement and price alerts.

HTTP
POST /api/v1/workspaces/{workspace_id}/model-migrations/preview
{"source_model":"provider/old","target_model":"provider/new"}

POST /api/v1/workspaces/{workspace_id}/model-migrations/apply
{"preview_id":"mmig-returned-id","selected":["preset:pst-returned-id"],"confirm":true}

GET /api/v1/workspaces/{workspace_id}/model-migrations
AUTHENTICATION

Use virtual API keys

Send your AIDMX key as a Bearer token. Virtual keys isolate applications and can enforce prepaid budgets, rate limits, model allowlists, and provider allowlists.

http
Authorization: Bearer mmk-••••••••

Inference API keys use the mmk- prefix. Previously issued keys still follow their original disablement, expiry and rotation rules.

Customer identity verification belongs to the organization and is shared by its members and workspaces. All seven regions require verification by default before recharging or using organization inference keys; incomplete or revoked verification returns 403. Signing in or verifying an email does not verify identity. An organization owner or administrator completes Organization management → Identity verification.

Use an mmk- inference key for model calls and a personal account session for accounts, recharge, saved conversations and organization governance. Hosted consoles keep the session in a secure cookie; do not copy sign-in credentials into an SDK. An urm- management key only performs scoped workspace administration and cannot call models or operate the wallet. Workspace management uses /api/v1/workspaces/{workspace_id}/...; an inference key is bound to its workspace and cannot switch workspaces through X-ModelMix-Workspace.

Parameters and model capabilities

Use the fields for your chosen protocol. Check model details for input types, tools, structured output, context and output limits. Endpoints for the same model may support different parameters.

Thinking controls and effort

Chat and Creative Studio offer thinking controls supported by the selected model. Reasoning-only models cannot disable thinking, and available effort levels vary. For the API, use reasoning.enabled / reasoning.effort or supported native fields. Do not mix reasoning with enable_thinking, thinking or reasoning_effort, or send contradictory preferences.

json
{
  "model": "MODEL_ID_SUPPORTING_THINKING_OFF",
  "messages": [{"role": "user", "content": "Hello"}],
  "reasoning": {"enabled": false},
  "max_tokens": 256
}

Output limits

Use max_tokens or supported max_completion_tokens with Chat Completions, max_output_tokens with Responses, and generationConfig.maxOutputTokens with Google. Set one limit for the chosen protocol. Omitted limits use model defaults; a larger explicit request must fit the endpoint's published output and context limits. Tool definitions, history and images also consume input capacity.

Some Bailian Responses models cannot cap combined reasoning and answer tokens with max_completion_tokens while thinking is enabled. Follow the error guidance to use max_tokens for the answer limit or choose a model supporting the requested control. Check the error and model capabilities before retrying.

PROVIDER ROUTING

Route with intent

The provider object filters and ranks eligible endpoints before a request is sent. Explicit constraints always win over learned performance.

json
{
  "model": "YOUR_CHAT_MODEL_ID",
  "provider": {
    "order": ["YOUR_PRIMARY_PROVIDER", "YOUR_BACKUP_PROVIDER"],
    "sort": "latency",
    "zdr": true,
    "allow_fallbacks": true
  }
}

Replace YOUR_CHAT_MODEL_ID and provider placeholders with a current catalog model and its endpoint provider IDs. GET /v1/models/{model_id}/endpoints lists endpoints. order sets preference; only restricts eligible providers. zdr: true removes endpoints that do not meet zero-retention requirements and can leave no eligible route.

sortprice · latency · throughput · exacto
only / ignoreFilter provider slugs
zdrZero data retention only
max_priceCap input and output cost

When provider.sort is omitted, workspace routing defaults apply. The default balanced strategy combines price, latency, endpoint weights and priorities. Explicit sort accepts price, latency, throughput and exacto; balanced names the default strategy and is not a valid request sort value. exacto sorting is not a general model quality leaderboard; evaluate it for your application.

AUTO ROUTER

Choose models by task and cost tier

Use modelmix/auto for task classification, model selection and cross-model fallbacks. Choose a cost band with cost_tier: low, medium, high, xhigh or max. The default is medium. Provider sorting applies after model selection.

json
{
  "model": "modelmix/auto",
  "messages": [{"role": "user", "content": "Debug this Python exception"}],
  "session_id": "conversation-123",
  "plugins": [{
    "id": "auto-router",
    "cost_tier": "medium",
    "allowed_models": ["qwen/*", "zhipu/*", "deepseek/*"],
    "excluded_models": ["zhipu/glm-4.7"]
  }]
}

Automatic selection considers the task, cost tier and the last seven days of completed usage on ModelMix, with catalog defaults when data is missing. It is not a general model quality ranking and still respects workspace and key restrictions on models, providers and privacy.

A conversation prefers its previous model while it remains among the top three eligible candidates. Session preferences expire after five minutes without a successful request. Explicit restrictions always apply. Audio and video generation still require an explicit model.

Use the x-request-id response header to inspect routing, provider attempts, delivery and settlement in Activity. Workspace permissions govern Console routing settings.

FALLBACKS

Design for failure

Use models to provide a prioritized fallback chain. AIDMX first exhausts healthy endpoints for the primary model, then advances to the next model.

json
{
  "model": "YOUR_PRIMARY_CHAT_MODEL_ID",
  "models": [
    "YOUR_BACKUP_CHAT_MODEL_ID"
  ]
}

Primary and fallback models must be enabled for the current region and key and satisfy this request's capability, price and privacy constraints. Replace the example placeholders; fallback lists do not bypass those restrictions.

Streaming and interrupted delivery

Set stream=true for streaming in the selected protocol. Save x-request-id to look up its status in Activity. Interrupted delivery can still incur charges; inspect the original request before generating again.

API reference and troubleshooting →

Record, transcribe and download speech

Open Chat, choose Audio above the composer, switch the audio action to transcription and select an available model. Record and preview locally for up to two minutes, or upload WAV, MP3 or FLAC up to 7 MiB. Recording requires HTTPS and microphone permission. Audio stays in the current tab without model charges until you submit transcription. Hiding or leaving the page interrupts and discards capture.

Web chat uses your signed-in account without manually connecting an inference key. Confirm the workspace and price before submitting paid transcription, then review the result before inserting it into a draft. If submission is uncertain, query the original task and check Activity before another request. Choose Audio → Speech to generate speech from text, with authenticated playback, download and saving to Files; download retries never regenerate.

Realtime transcription is available in the playground for audio models supporting it. Audio is sent immediately to the selected provider for up to 120 seconds and charged by actual usage. This converts speech to text; it is not a two-way realtime voice call.

MODEL CONFIGURATION

Before configuring a model

Follow these steps to use text, image, audio, video, embedding and reranking models in your application. In ModelMix web Chat and Creative Studio, sign in and choose your workspace and model; those pages use your account automatically. External applications and the examples below use an inference key.

  1. Sign into the console, select the organization and workspace, complete any required identity verification, and confirm available balance or an active plan allowance.
  2. Open the model catalog and choose the task type. Check the model's input/output types, supported parameters, limits and price. Copy its complete model ID, rather than its display name or a provider's upstream model name.
  3. Create an inference key in the same workspace. Check its model permissions, spending cap and expiry. Use the mmk- key as the API key in your application.
  4. For an OpenAI-compatible client, enter the base URL below, your inference key and the selected model ID. If the tool asks for a complete request URL instead, append the operation path once. Confirm the tool supports the task: a text-only chat client may not offer image or video generation.
Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
Base URLYeshttps://stg-api.aidmx.net/v1
API KeyYesYour workspace's mmk- inference key; keep it in protected application configuration.
modelYesThe complete ID copied from the model catalog; each task needs an appropriate model.

The base URL ends in /v1. Model discovery uses GET /v1/models on the same base URL. Do not append /chat/completions to a Base URL field. Website passwords and management keys cannot replace an inference key.

Prepare the Python examples

Use Python 3 and install requests. In the same terminal, set the base URL and your real inference key. Each example is a complete file; replace its uppercase model/voice placeholders before running. On systems where Python 3 is named python3, use python3 in these commands.

bash · macOS / Linux
python -m pip install requests
export MODELMIX_BASE_URL="https://stg-api.aidmx.net/v1"
export MODELMIX_API_KEY="mmk-REPLACE_WITH_YOUR_KEY"
Windows PowerShell setup
powershell
python -m pip install requests
$env:MODELMIX_BASE_URL = "https://stg-api.aidmx.net/v1"
$env:MODELMIX_API_KEY = "mmk-REPLACE_WITH_YOUR_KEY"

Find model IDs available to your key

The model list defaults to text output. Use output_modalities=all to include image, audio, video and vector output, and available_only=true to filter for callable configurations. To narrow the list, add task_type=chat, image, speech, transcription, video, embedding or rerank. Catalog availability is not a guarantee of live provider availability.

List models

Save as list_models.py, replace the model ID and placeholders, then run python list_models.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

response = checked(requests.get(
    BASE_URL + "/models", headers=HEADERS,
    params={"output_modalities": "all", "available_only": "true"},
    timeout=30,
))
for model in response.json()["data"]:
    print(model["task_type"], model["id"])
Run a small first request

Use a short message, one image or a short audio/video sample. Actual calls are billable. The examples do not automatically resend generation requests. If a request times out or its result is uncertain, check its request ID or saved task before submitting again. Keep keys out of public frontend code and shared examples.

Coze video workflows

For Console video tasks, import the OpenAPI below into Coze and configure the Authorization header with a Bearer inference key in the plugin’s credential settings. Save the task ID and poll the existing task using Retry-After or poll_after_seconds. When requires_action=true, wait for administrator reconciliation without resubmitting paid work.

https://stg-api.aidmx.net/api/v1/videos/openapi.json

Successful results can be downloaded while billing is pending. Keep the existing task when its result or charge is uncertain. expires_at=null means no automatic expiry is set and does not guarantee permanent result availability. Downloads and saves remain subject to permissions and artifact retention.

Text models: chat and text generation

Use a chat model for conversation, writing, translation and code. Begin with Chat Completions; use another protocol only if your client and the selected model support it.

First connection: complete the shared setup →

Configuration steps

  1. Choose task_type=chat in the catalog. Copy the model ID and check context, output limits and supported protocol.
  2. Configure the base URL, inference key and model ID in the client, or use POST /v1/chat/completions with the example below.
  3. Send one short message with the default model settings. After it works, add history, output limits, thinking settings or streaming one at a time.

Parameters

Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
modelYesA complete chat model ID.
messagesYesAn ordered array of role/content messages. Start with a user message; include prior user and assistant messages for later turns.
max_tokens / max_completion_tokensOptionalUse one field supported by the endpoint. It limits output tokens and must fit context/output limits. Omit it to use model defaults; some thinking models count reasoning tokens in the total.
temperature / top_pOptionalSampling controls, only when supported. Temperature is 0–2 and top_p is 0–1. Start with defaults and change one control at a time.
streamOptionaltrue returns SSE events. Your client must read incremental events through completion; false or omitted returns one JSON response.
reasoningOptionalUse enabled and/or effort only as supported in model details. Do not mix this object with enable_thinking, thinking or reasoning_effort.
response_format / toolsOptionalStructured output and client function tools require model support. Your application executes returned function calls and sends their results back.

Complete example: Chat Completions

Save as text_chat.py, replace the model ID and placeholders, then run python text_chat.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

MODEL = "CHAT_MODEL_ID_FROM_CATALOG"
response = checked(requests.post(
    BASE_URL + "/chat/completions", headers=HEADERS,
    json={
        "model": MODEL,
        "messages": [{"role": "user", "content": "Reply only: ModelMix connected."}],
    },
    timeout=180,
))
result = response.json()
print(result["choices"][0]["message"]["content"])
print("Usage:", result.get("usage"))
Optional complete example: streaming Chat Completions

Save as text_stream.py, replace the model ID and placeholders, then run python text_stream.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

import json

MODEL = "CHAT_MODEL_ID_FROM_CATALOG"
with requests.post(
    BASE_URL + "/chat/completions", headers=HEADERS,
    json={
        "model": MODEL,
        "messages": [{"role": "user", "content": "Write one sentence about the sea."}],
        "stream": True,
    },
    stream=True, timeout=(30, 180),
) as response:
    checked(response)
    response.encoding = "utf-8"
    complete = False
    for line in response.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        data = line[5:].strip()
        if data == "[DONE]":
            complete = True
            break
        event = json.loads(data)
        if event.get("error"):
            raise RuntimeError(event["error"])
        for choice in event.get("choices", []):
            print(choice.get("delta", {}).get("content") or "", end="", flush=True)
    print()
    if not complete:
        raise RuntimeError("Stream interrupted. Check this request in Activity before retrying.")
Optional complete example: Responses

Save as text_responses.py, replace the model ID and placeholders, then run python text_responses.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

MODEL = "RESPONSES_MODEL_ID_FROM_CATALOG"
response = checked(requests.post(
    BASE_URL + "/responses", headers=HEADERS,
    json={"model": MODEL, "input": "Reply only: ModelMix connected.", "store": False},
    timeout=180,
))
result = response.json()
for item in result.get("output", []):
    for part in item.get("content", []):
        if part.get("type") == "output_text":
            print(part["text"])
print("Usage:", result.get("usage"))

Verify the result

  1. Expect HTTP 200 and a reply containing ModelMix connected. For Chat Completions read choices[0].message.content; for Responses read output message content of type output_text.
  2. For streaming, verify that incremental text is visible and the final [DONE] arrives. An interrupted stream can already contain billable work.
  3. If a parameter returns 400, compare it with the selected model's supported parameters. The Responses example uses input and store:false; a Responses output cap uses max_output_tokens rather than Chat fields.

Examples print the HTTP status and x-request-id. Search that ID in Console Activity to check the model, status, usage and charge. Billing may still be pending when generation finishes. Errors and troubleshooting →

Image models: generate, understand and edit

Generating an image uses an image model. Understanding an image uses a chat model that accepts images. Editing additionally requires image-edit support; an image-capable chat model does not imply image generation or editing.

First connection: complete the shared setup →

Configuration steps

  1. Choose an image model for generation, a chat model with image input for understanding, or an image model with edit support for editing. Confirm input formats, output sizes and prices in model details.
  2. In web Chat choose Image, select the model and enter a prompt. In your application use /v1/images/generations for generation, /v1/chat/completions for understanding, or /v1/images/edits for editing.
  3. First request one image with default size. For upload examples place a small, real PNG named reference.png beside the script; use matching MIME types when changing formats.

Parameters

Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
modelYesUse a model matching generation, image understanding or editing as described above.
promptGeneration / editDescribe subject, setting and style; for edits state what should change and what should stay.
nOptionalNumber of output images; begin with 1. Model limits and prices apply to each generated image.
size / qualityOptionalChoose an advertised size/quality. A value such as 1024x1024 is only valid for models that support it. Omit both for the first request.
response_formatOptionalWhere supported: url for an image URL, b64_json for Base64 bytes. The example saves either response without requiring a particular output mode.
messages[].contentUnderstandingUse text and image_url content parts. image_url.url may be a supported HTTPS URL or a data URL with MIME type and Base64 content.
imageEditingUpload the image as multipart file data. Do not manually set the multipart Content-Type; requests adds the boundary.
seed / watermarkOptionalOnly set these when advertised by the selected model. A fixed seed is not a guarantee of identical output across models or versions.

Complete example: generate and save an image

Save as image_generate.py, replace the model ID and placeholders, then run python image_generate.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

MODEL = "IMAGE_MODEL_ID_FROM_CATALOG"
response = checked(requests.post(
    BASE_URL + "/images/generations", headers=HEADERS,
    json={
        "model": MODEL,
        "prompt": "A red sailboat on a calm lake at sunrise, watercolor.",
        "n": 1,
    },
    timeout=180,
))
result = response.json()

def save_image(result):
    import base64
    from pathlib import Path
    from urllib.parse import urljoin, urlsplit

    image = result["data"][0]
    if image.get("b64_json"):
        content = base64.b64decode(image["b64_json"], validate=True)
    else:
        url = urljoin(BASE_URL + "/", image["url"])
        same_origin = urlsplit(url)[:2] == urlsplit(BASE_URL)[:2]
        # Only ModelMix receives your ModelMix key.
        content = checked(requests.get(
            url, headers=HEADERS if same_origin else {},
            timeout=180, allow_redirects=False,
        )).content
    suffix = (
        ".png" if content.startswith(b"\x89PNG") else
        ".jpg" if content.startswith(b"\xff\xd8") else
        ".webp" if content[8:12] == b"WEBP" else ".bin"
    )
    path = Path("modelmix-image" + suffix)
    path.write_bytes(content)
    print("Saved:", path.resolve())

save_image(result)
Complete example: understand a local image

Save as image_understand.py, replace the model ID and placeholders, then run python image_understand.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

import base64
from pathlib import Path

MODEL = "CHAT_MODEL_ID_WITH_IMAGE_INPUT"
image = base64.b64encode(Path("reference.png").read_bytes()).decode("ascii")
response = checked(requests.post(
    BASE_URL + "/chat/completions", headers=HEADERS,
    json={
        "model": MODEL,
        "messages": [{"role": "user", "content": [
            {"type": "text", "text": "Describe the main subject and its color in this image."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64," + image}},
        ]}],
    },
    timeout=180,
))
print(response.json()["choices"][0]["message"]["content"])
Complete example: edit an uploaded image

Save as image_edit.py, replace the model ID and placeholders, then run python image_edit.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

MODEL = "IMAGE_MODEL_ID_WITH_EDIT_SUPPORT"
with open("reference.png", "rb") as image:
    response = checked(requests.post(
        BASE_URL + "/images/edits", headers=HEADERS,
        data={"model": MODEL, "prompt": "Change the boat to blue; keep the composition.", "n": "1"},
        files={"image": ("reference.png", image, "image/png")},
        timeout=180,
    ))
result = response.json()

def save_image(result):
    import base64
    from pathlib import Path
    from urllib.parse import urljoin, urlsplit

    image = result["data"][0]
    if image.get("b64_json"):
        content = base64.b64decode(image["b64_json"], validate=True)
    else:
        url = urljoin(BASE_URL + "/", image["url"])
        same_origin = urlsplit(url)[:2] == urlsplit(BASE_URL)[:2]
        # Only ModelMix receives your ModelMix key.
        content = checked(requests.get(
            url, headers=HEADERS if same_origin else {},
            timeout=180, allow_redirects=False,
        )).content
    suffix = (
        ".png" if content.startswith(b"\x89PNG") else
        ".jpg" if content.startswith(b"\xff\xd8") else
        ".webp" if content[8:12] == b"WEBP" else ".bin"
    )
    path = Path("modelmix-image" + suffix)
    path.write_bytes(content)
    print("Saved:", path.resolve())

save_image(result)

Verify the result

  1. Generation should return data with an image and create a local modelmix-image file. Open it and check the red boat and requested scene. Downloads may need the original ModelMix key for a ModelMix URL; never send that key to an external image host.
  2. For understanding, use a simple image with a clearly recognizable subject/color and compare the text reply with it. For editing, compare the input and result to confirm the change.
  3. If upload fails, check the actual file format, MIME type, size and the model's edit/input support. If a download fails after generation, recover that result rather than generating another image immediately.

Examples print the HTTP status and x-request-id. Search that ID in Console Activity to check the model, status, usage and charge. Billing may still be pending when generation finishes. Errors and troubleshooting →

Audio models: speech synthesis and transcription

Speech synthesis converts text to audio and uses task_type=speech. Transcription converts audio to text and uses task_type=transcription. Choose a model for the required direction.

First connection: complete the shared setup →

Configuration steps

  1. Choose a speech or transcription model. Check voices, languages, audio formats, input limits and the charging unit before calling it.
  2. In web Chat choose Audio → Speech or Transcription, then select a model. External speech calls use POST /v1/audio/speech; transcription uses POST /v1/audio/transcriptions.
  3. For synthesis replace the voice placeholder with a valid voice for that model and confirm WAV output support. For transcription place a short WAV file named sample.wav beside the script.

Parameters

Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
modelYesUse a speech model for synthesis or a transcription model for ASR.
inputSpeechText to speak. Start with a short sentence. Web speech input accepts at most 3,000 characters; the model may have a lower limit.
voiceSpeechAn exact voice ID supported by this model, not its display name. Voice IDs and access vary by model; do not copy a voice from another provider.
response_formatOptionalSynthesis returns audio bytes, e.g. wav/mp3 when supported. Transcription commonly uses json/text; verbose_json and timestamps require explicit model support. Match the saved file extension to the chosen format.
speed / instructionsOptionalSynthesis speed and style instructions are model-specific; omit them until the basic call succeeds.
fileTranscriptionThe actual audio file in multipart form data, rather than a local path string. Web uploads support WAV/MP3/FLAC up to 7 MiB; microphone recording lasts up to two minutes.
languageOptionalFor models accepting it, an input language code such as zh or en. Otherwise omit it for automatic recognition.

Recording and realtime transcription →

Complete example: generate a WAV file

Save as audio_speech.py, replace the model ID and placeholders, then run python audio_speech.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

from pathlib import Path

MODEL = "SPEECH_MODEL_ID_FROM_CATALOG"
VOICE = "VOICE_ID_SUPPORTED_BY_THIS_MODEL"
response = checked(requests.post(
    BASE_URL + "/audio/speech", headers=HEADERS,
    json={
        "model": MODEL,
        "input": "Welcome to ModelMix. This is a speech synthesis test.",
        "voice": VOICE,
        "response_format": "wav",
    },
    timeout=180,
))
Path("modelmix-speech.wav").write_bytes(response.content)
print("Saved: modelmix-speech.wav; content-type:", response.headers.get("content-type"))

Complete example: transcribe an uploaded WAV file

Save as audio_transcribe.py, replace the model ID and placeholders, then run python audio_transcribe.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

MODEL = "TRANSCRIPTION_MODEL_ID_FROM_CATALOG"
with open("sample.wav", "rb") as audio:
    response = checked(requests.post(
        BASE_URL + "/audio/transcriptions", headers=HEADERS,
        data={"model": MODEL, "response_format": "json"},
        files={"file": ("sample.wav", audio, "audio/wav")},
        timeout=180,
    ))
print(response.json()["text"])

Verify the result

  1. Synthesis should save modelmix-speech.wav. Play it locally and confirm that the spoken words match input and that the file format matches its extension.
  2. For transcription, record a clear short sentence and check that the JSON text field captures it. Silence, background noise and unsupported languages can affect recognition.
  3. A voice or output-format error usually requires choosing a value supported by this model. For recording and realtime transcription, follow the separate recording guide; realtime transcription is speech-to-text, not a two-way voice call.

Examples print the HTTP status and x-request-id. Search that ID in Console Activity to check the model, status, usage and charge. Billing may still be pending when generation finishes. Errors and troubleshooting →

Video models: create, poll and download

Video generation is asynchronous: create a task once, keep its ID, retrieve its status, and download the completed content. Text-to-video and reference-image support vary by model.

First connection: complete the shared setup →

Configuration steps

  1. Choose task_type=video and check duration, resolution, aspect ratio, reference inputs and price. The example uses four seconds at 1280x720; choose a model supporting those values or change them together.
  2. In web Chat choose Video, then the model, prompt, duration and aspect ratio. Add a reference image only when offered by the model. In an application create a task with POST /v1/videos.
  3. Keep the returned id. Use GET /v1/videos/{id} for status and GET /v1/videos/{id}/content for the result with the original key. These calls do not create another video.

Parameters

Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
model / promptYesThe video model ID and a description of the scene, movement and desired style.
secondsSet explicitlyA supported output duration. The standard request uses a string such as "4"; supported durations differ by model.
sizeSet explicitlyA supported width×height string such as 1280x720, not an aspect-ratio string such as 16:9. Select it together with the model's resolution/duration limits.
input_referenceOptionalAn uploaded reference image for models supporting image-to-video. The example sends multipart data. Check required dimensions, format and reference role before uploading.
generate_audio / seed / watermarkOptionalOnly use fields explicitly supported by the selected model; a video model may not generate audio.
id / statusResponseid identifies the original task. Poll until completed; failed/cancelled requires inspecting the error rather than downloading a successful result.
Retry-AfterResponse headerFollow the suggested polling delay when present. The example polls every five seconds otherwise and stops waiting after a bounded number of polls.

Complete example: create, resume and download video

Save as video_generate.py, replace the model ID and placeholders, then run python video_generate.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

import json
import time
from pathlib import Path
from urllib.parse import quote

MODEL = "VIDEO_MODEL_ID_FROM_CATALOG"
STATE = Path("modelmix-video-task.json")

if STATE.exists():
    task = json.loads(STATE.read_text(encoding="utf-8"))
    if task["base_url"] != BASE_URL:
        raise RuntimeError("Use the same ModelMix base URL as the saved task.")
    task_id = task["id"]
else:
    payload = {
        "model": MODEL,
        "prompt": "A red sailboat crossing a calm lake at sunrise.",
        "seconds": "4",
        "size": "1280x720",
    }
    created = checked(requests.post(
        BASE_URL + "/videos", headers=HEADERS, json=payload, timeout=180,
    )).json()
    task_id = created["id"]
    STATE.write_text(json.dumps({"id": task_id, "base_url": BASE_URL}),
                     encoding="utf-8")
    print("Saved task:", task_id)

# Restarting this program resumes the saved task; it does not create a new video.
task_url = BASE_URL + "/videos/" + quote(task_id, safe="")
for attempt in range(120):
    response = checked(requests.get(task_url, headers=HEADERS, timeout=60))
    task = response.json()
    print("Task:", task_id, "status:", task["status"])
    if task["status"] == "completed":
        content = checked(requests.get(
            task_url + "/content", headers=HEADERS, timeout=180,
        )).content
        Path("modelmix-video.mp4").write_bytes(content)
        print("Saved: modelmix-video.mp4")
        break
    if task["status"] in {"failed", "cancelled", "canceled"}:
        raise RuntimeError(task.get("error") or task["status"])
    try:
        delay = float(response.headers.get("Retry-After", "5"))
    except ValueError:
        delay = 5
    time.sleep(max(1, min(delay, 60)))
else:
    print("Still pending. Run this same file again to resume the saved task.")
Optional complete example: reference-image video

Save as video_reference.py, replace the model ID and placeholders, then run python video_reference.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

import json
import time
from pathlib import Path
from urllib.parse import quote

MODEL = "VIDEO_MODEL_ID_FROM_CATALOG"
STATE = Path("modelmix-video-task.json")

if STATE.exists():
    task = json.loads(STATE.read_text(encoding="utf-8"))
    if task["base_url"] != BASE_URL:
        raise RuntimeError("Use the same ModelMix base URL as the saved task.")
    task_id = task["id"]
else:
    payload = {
        "model": MODEL,
        "prompt": "A red sailboat crossing a calm lake at sunrise.",
        "seconds": "4",
        "size": "1280x720",
    }
    with open("reference.png", "rb") as image:
        created = checked(requests.post(
            BASE_URL + "/videos", headers=HEADERS, data=payload,
            files={"input_reference": ("reference.png", image, "image/png")},
            timeout=180,
        )).json()
    task_id = created["id"]
    STATE.write_text(json.dumps({"id": task_id, "base_url": BASE_URL}),
                     encoding="utf-8")
    print("Saved task:", task_id)

# Restarting this program resumes the saved task; it does not create a new video.
task_url = BASE_URL + "/videos/" + quote(task_id, safe="")
for attempt in range(120):
    response = checked(requests.get(task_url, headers=HEADERS, timeout=60))
    task = response.json()
    print("Task:", task_id, "status:", task["status"])
    if task["status"] == "completed":
        content = checked(requests.get(
            task_url + "/content", headers=HEADERS, timeout=180,
        )).content
        Path("modelmix-video.mp4").write_bytes(content)
        print("Saved: modelmix-video.mp4")
        break
    if task["status"] in {"failed", "cancelled", "canceled"}:
        raise RuntimeError(task.get("error") or task["status"])
    try:
        delay = float(response.headers.get("Retry-After", "5"))
    except ValueError:
        delay = 5
    time.sleep(max(1, min(delay, 60)))
else:
    print("Still pending. Run this same file again to resume the saved task.")

Verify the result

  1. After the first successful submission, confirm that modelmix-video-task.json contains the returned ID. Restarting either example reads that file and continues the same task. Keep using the original key and base URL.
  2. Expect completed, then a playable modelmix-video.mp4 with the requested scene and duration. Waiting or timing out locally does not establish that generation failed; query the saved task again.
  3. To deliberately generate another video, move or remove the saved task file after checking the previous result and charge. If submission times out before an ID is saved, check Activity first; immediately running it again could submit a second paid task.

Examples print the HTTP status and x-request-id. Search that ID in Console Activity to check the model, status, usage and charge. Billing may still be pending when generation finishes. Errors and troubleshooting →

Embedding models: convert text to vectors

Embeddings represent text as numeric vectors for search and similarity. The response is a vector per input, rather than a chat reply or a set of ranked documents.

First connection: complete the shared setup →

Configuration steps

  1. Choose task_type=embedding. Include output_modalities=all when discovering models, and check supported dimensions, encoding and batch/context limits.
  2. Configure the base URL and inference key, then use POST /v1/embeddings. Start with two short strings, the default dimensions and float encoding.
  3. Use the same model, dimensions and preprocessing for stored documents and later queries. Changing the embedding model or dimensions usually requires rebuilding the stored vectors.

Parameters

Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
modelYesThe complete embedding model ID.
inputYesOne nonempty string or an array of strings. Batch limits depend on the model; split large documents in your application before sending them.
dimensionsOptionalA supported output dimension as an integer. Omit it for the default; do not assume every model permits arbitrary dimensions.
encoding_formatOptionalfloat returns numeric arrays and is easiest to inspect. base64, where supported, requires decoding to the model's vector representation before calculation.
input_type / text_type / instructOptionalSome models distinguish query/document inputs or accept retrieval instructions. Use only the names and values advertised for that model; they are not universal embedding parameters.
data[].index / embeddingResponseindex identifies the original input and embedding contains its vector. Preserve this mapping when storing batches.

Complete example: generate and validate vectors

Save as embeddings.py, replace the model ID and placeholders, then run python embeddings.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

import math

MODEL = "EMBEDDING_MODEL_ID_FROM_CATALOG"
texts = ["How do I create an API key?", "Create a key in the ModelMix console."]
response = checked(requests.post(
    BASE_URL + "/embeddings", headers=HEADERS,
    json={"model": MODEL, "input": texts, "encoding_format": "float"},
    timeout=180,
))
result = response.json()
rows = sorted(result["data"], key=lambda item: item["index"])
assert [item["index"] for item in rows] == list(range(len(texts)))
vectors = [item["embedding"] for item in rows]
assert vectors and len(vectors[0]) > 0
assert len({len(vector) for vector in vectors}) == 1
assert all(math.isfinite(value) for vector in vectors for value in vector)
print("Vectors:", len(vectors), "dimensions:", len(vectors[0]))
print("First vector preview:", vectors[0][:5])
print("Usage:", result.get("usage"))

Verify the result

  1. The two inputs should produce two vectors with indices 0 and 1. The example checks that dimensions agree and all components are finite numbers.
  2. Compare the reported dimension with model details or your explicit dimensions value. Your vector database schema must use the same dimension.
  3. To check retrieval quality, embed a query and several clearly related/unrelated texts with the same settings and compare similarity. A successful HTTP response alone does not establish search quality.

Examples print the HTTP status and x-request-id. Search that ID in Console Activity to check the model, status, usage and charge. Billing may still be pending when generation finishes. Errors and troubleshooting →

Reranking models: rank candidate documents

Reranking scores documents against a query. Retrieve candidate documents first, then ask the reranker to order them. It does not retrieve documents by itself or generate a chat answer.

First connection: complete the shared setup →

Configuration steps

  1. Choose task_type=rerank and check query length, document count/length, supported parameters and pricing.
  2. Use POST /v1/rerank with a clear query and a small array of candidate strings. Keep their original order so returned indices can be mapped back to your documents.
  3. Set top_n to the number of results you need, no greater than the number of candidates. Start with three candidates and two results as in the example.

Parameters

Start with required fields. Add optional fields only when the model supports them.
ParameterRequiredHow to set it
modelYesThe complete rerank model ID, rather than a chat or embedding model.
queryYesA nonempty search question or statement of relevance, e.g. how to create a ModelMix API key.
documentsYesAn array of candidate document strings. Begin with plain text and keep within the model's batch and context limits.
top_nOptionalA positive integer specifying how many highest-ranked results to keep. Choose a value no larger than documents.length.
return_documentsOptionalSet true to request document text in results where supported. With false, map each returned index to your original documents.
results[].indexResponseThe original input index, starting at zero; it is not the position in the new ranking.
results[].relevance_scoreResponseHigher scores indicate greater relevance within this result. Do not assume identical score scales across different models.

Complete example: rerank and map results to documents

Save as rerank.py, replace the model ID and placeholders, then run python rerank.py.

python
import os
import requests

BASE_URL = os.environ.get("MODELMIX_BASE_URL", "https://stg-api.aidmx.net/v1").rstrip("/")
API_KEY = os.environ["MODELMIX_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}

def checked(response):
    print("HTTP:", response.status_code,
          "request_id:", response.headers.get("x-request-id", ""))
    if not 200 <= response.status_code < 300:
        raise RuntimeError(response.text)
    return response

MODEL = "RERANK_MODEL_ID_FROM_CATALOG"
documents = [
    "Open the ModelMix console, choose API keys, and create an inference key.",
    "A sailboat moves across a lake at sunrise.",
    "Keep each application's API key in its protected configuration.",
]
response = checked(requests.post(
    BASE_URL + "/rerank", headers=HEADERS,
    json={
        "model": MODEL,
        "query": "How do I create a ModelMix API key?",
        "documents": documents,
        "top_n": 2,
        "return_documents": False,
    },
    timeout=180,
))
rows = response.json()["results"]
assert len(rows) == 2
indices = [row["index"] for row in rows]
assert len(set(indices)) == len(indices)
assert all(0 <= index < len(documents) for index in indices)
scores = [row["relevance_score"] for row in rows]
assert scores == sorted(scores, reverse=True)
for row in rows:
    print(row["index"], row["relevance_score"], documents[row["index"]])

Verify the result

  1. The example should return two results with unique valid indices and descending relevance scores. It prints the original document beside each score.
  2. Check that the key-creation instructions rank ahead of the unrelated sailboat text. If not, review query wording, document content and whether the model suits your language/task.
  3. If you get a length or batch error, shorten individual candidates or reduce their count. To compare query quality, keep the candidate set and model settings fixed.

Examples print the HTTP status and x-request-id. Search that ID in Console Activity to check the model, status, usage and charge. Billing may still be pending when generation finishes. Errors and troubleshooting →

Standard batches

Upload JSONL with purpose=batch through /v1/files, then submit input_file_id, endpoint and completion_window to /v1/batches. A file uses one published model, one endpoint and up to 100 unique requests. Save the task ID and use the original key to retrieve status and result files. Actual usage determines charges. You can close the page after submission; pending status is not a reason to resubmit.

API reference and troubleshooting →
CHAT

Save conversations and compare models

Switch between Chat, Image, Video and Audio above the composer; only types with available models in the workspace appear. Choose a type and model, then enter your description and parameters. Audio supports microphone or WAV/MP3/FLAC transcription, reviewed insertion into a draft and speech synthesis. Record up to two minutes or upload up to 7 MiB; speech accepts 3,000 characters and image/video descriptions 4,000. Each generation is billed separately; recording, previewing, inserting, downloading and saving do not generate again.

Open Chat after signing into the console and create or restore a private conversation. Web chat uses your signed-in account without manually connecting an inference key; switching workspaces applies that workspace's permissions and policies. In Chat mode, compare up to three models and choose one answer as the next turn's context. Each model is billed separately; Activity records actual charges. External apps and SDKs still need a workspace inference key.

Video mode supports first-frame references, duration and aspect ratio where the model permits them. Track media in its chat result card or recover it from Media history, where you can filter by type, download, save to Files and reuse descriptions or supported references. Reading history never regenerates media. For uncertain submissions, check the original task and Activity first.

Chat generation runs in the background, with streaming previews, result recovery after closing the page and explicit cancellation. Reopening a conversation or resuming a subscription reads the original job without repeating a paid request. Cancellation or interruption may still incur charges for work already performed; check Activity when a job's state is uncertain. Generation recovery records last 24 hours; answers saved into the conversation follow its retention.

Conversation content is encrypted and isolated by user and workspace until deleted. Each conversation supports up to 40 turns and 512 KiB, with existing document/image attachments, instructions, parameters and tools. Reloading or retrying a save never automatically repeats inference.

Use the branch map to navigate originals, siblings and descendants. Preview and confirm the title, messages and selected answers before creating a read-only link lasting 1, 7 or 30 days. Instructions, unselected answers and attachment files are excluded, but message text may still contain private information. Later edits leave the snapshot unchanged. Replacing or revoking the link, or deleting its source, disables the old link. Copies already kept by readers cannot be recalled.

/api/v1/chat/sessions uses account-session authentication. Saving requires expected_revision and a unique operation_id. This application API is separate from model inference.

AI assistant and workspace collaboration

Desktop and cloud clients

Sign into the console, choose your workspace, then open Client → Sign in to desktop or Sign in to cloud client. The single-use sign-in link expires after two minutes. If the desktop app does not open, the console takes you to Downloads. You can also sign into the installed client with your ModelMix account; download the build for your environment.

Client downloads → · Cloud subscriptions →

Cloud runs and shared results

In Workbench → Agents & collaboration, a workspace administrator first enables the service and configures organization inference authorization in Service settings. Choose New run, select a project, permitted input files or a template, and set execution resources, spending limit and maximum runtime. After creating the instance, click Open agent in the list and enter your specific task instructions in the conversation. Queued runs wait for execution capacity; inspect the existing instance before creating another.

A cloud run provides an execution environment and can contain multiple conversations. The client’s conversation list shows individual chats, while the console lists cloud runs and their usage. Local client conversations are not listed in the console. To save instructions for automatic execution, create an organization automation; each scheduled, manual or event trigger sends those instructions to the agent.

Run conversation history is private. Publish selected results or templates to make a workspace copy available to members, with version history. Stopping a run can still leave already incurred model charges. Deleting a run removes its private history and cloud task files; project files and published workspace copies remain. Cloud resource subscriptions do not include model inference fees.

Open Agents & collaboration →

Create with Creative Studio

Choose Workbench → Creative studio in the console to open a new tab. Sign in with your ModelMix account and confirm the workspace. Models, permissions and billing use ModelMix automatically. Projects, canvases, agent history and media are isolated by user and workspace; membership in the same workspace does not automatically share a private canvas.

  1. Create or open a project, add text, image, video or audio nodes, and choose a model offered for that task. Check prices and generation settings before submitting.
  2. Reference images, video, audio, output duration, resolution and aspect ratio depend on the selected model. Follow the options and reference-processing notices shown on the page. Selecting Follow reference image means you do not need to enter a separate aspect ratio.
  3. Wait for generation and saving to complete. If generation succeeds but the canvas is not saved, recover the original task and finish saving; do not resubmit paid generation. Reopening a project restores saved content, but a new generation is a new billable operation.

Creative Studio and Agent Cloud share the organization resource pool and one 7-day trial. Project files and creative assets use the included shared storage by their actual size. Model generation is billed separately. Check your subscription and remaining balance before starting a paid generation.

Open Creative studio →

Operations workbench and channel roles

The operations workbench is a separate portal for assigned channel accounts. Register a normal ModelMix account first, then have an authorized administrator assign your channel role. Sign in at the workbench address supplied by your operator using that account. Ordinary customer registration and organization ownership do not grant channel access.

  • MB administrators create operations centers from the center list. Center administrators create custom roles in Role management, then assign one or more roles when adding or editing employees. Roles can separately allow performance, customer, quote, team and staff operations within that center. The built-in read-only role remains available.
  • Members add and edit direct agents from the agent list. Agents sign in to their user list. Centers, members and agents can each view customers throughout their own branch, including customers acquired by downstream referrals. Invitation links carry an eight-character code using uppercase letters and digits, excluding 0, 1, I, L and O.
  • Employees can only delegate permissions they hold, and workbench roles do not grant MB or OPS access. Role changes apply to the next request. Preview and confirm discount changes within the range allowed on the page. The last center administrator must hand over before being disabled or demoted.

If access is denied, ask your channel administrator to check the assigned identity and staff permissions. Channel administrators do not set or replace a user's account password.

PRIVACY

Make policy executable

Prompts and responses are not stored by default. Per-request controls can require zero-retention endpoints or deny providers that collect data.

Account region and data location

China / United States account regions determine wallet currency, model availability and service policies. They do not guarantee processing or storage within either country. Model, file and search services may process data in different places; confirm any residency requirement with support before use.

Disabling prompt logs or selecting zero-retention endpoints does not guarantee a data location or delete explicitly saved chats, files or billing records. Provider retention, gateway content logging and business-record retention are separate controls.

Organization and member request policies

Workspace administrators manage local guardrails; organization owners/admins manage policies across all current and future workspaces. Organization and workspace rules intersect, inherited policies cannot be weakened locally, and blocks take precedence over redaction.

all_keys covers service and personal keys in scope. member_ids covers selected members’ current and future personal keys, excluding service keys they created. Workspace policies may combine key_ids and member_ids; organization policies support all_keys or member_ids.

Personal sessions need administrator access in the relevant scope. Workspace guardrails also accept an explicitly scoped urm- management key: guardrails:read permits reads, dry runs and assignment previews; guardrails:write permits creation, updates and archival. Management keys cannot operate organization guardrails; inference keys and system tokens cannot manage guardrails. Each scope permits 100 active policies, up to 500 keys and 500 members. Updates and archival require expected_revision; conflicts return 409 without overwriting the policy.

Previews describe current inventory and return at most 100 sample keys with complete counts. They do not validate inference access, balances, expiration or upstream availability. Dry-run samples create no events or supplier calls; enforcement events retain rule metadata without matched prompt content.

http
GET /api/v1/workspaces/{workspace_id}/guardrails/targets
POST /api/v1/workspaces/{workspace_id}/guardrails/preview
GET /api/v1/workspaces/{workspace_id}/guardrails/effective?key_id=key-id
POST /api/v1/organizations/{organization_id}/guardrails
{
  "name": "Team privacy", "all_keys": false,
  "key_ids": [], "member_ids": ["user-id"],
  "config": {"providers": {"zdr": true, "data_collection": "deny"}}
}
PATCH /api/v1/organizations/{organization_id}/guardrails/{id}
{"expected_revision": 1, "name": "Updated team privacy"}
DELETE /api/v1/organizations/{organization_id}/guardrails/{id}?expected_revision=2

spending supports shared daily, weekly, monthly and lifetime caps in the organization's billing currency and UTC windows. In-flight estimates, pending charges and actual wallet charges, including BYOK service fees, count toward each cap. The reserved field includes unsettled capacity and does not imply wallet funds are frozen for new inference. Assignment edits retain attributed usage. GET /api/v1/workspaces/{workspace_id}/guardrails/budgets reports limits, spent, reserved and remaining amounts; the same suffix works for organization scope. Limits below usage plus reservations return 409, and over-budget inference returns 402 before contacting a supplier.

prompt_injection.allowlist accepts up to 20 name/text exceptions, matched exactly against one complete text field within that policy. Case and surrounding whitespace must match. Other policies and sensitive-data checks still apply; events retain exception names only. Content dry runs do not evaluate spending or reserve funds: spending_evaluated is always false.

Plans, daily points and storage

Choose ModelMix in Product subscriptions to view offers, prices and rights available to the current organization. An empty list means no plans are available for purchase. Organization owners or users with billing administration access can preview an order and pay with the wallet or an offered payment provider. Refresh the order and subscription to confirm an active period; pending payment or paid-but-not-activated does not make rights available.

Open product subscriptions →

An active ModelMix plan includes daily points and organization-shared storage. Points reset at midnight Asia/Shanghai without carryover; their monetary value follows the purchased rights and currency. They offset eligible model usage and are not withdrawable or refundable wallet principal. Plan rights show used, reserved and remaining points; actual usage determines final consumption. Accounts without a subscription retain pay-as-you-go wallet billing.

Use the organization wallet when points run out or the plan expires is a separate switch, off by default. While off, insufficient points or an expired previously activated plan can return 402 even with a positive wallet balance. Check the plan and allowance before renewing or explicitly enabling wallet fallback. Wallet and key, workspace and guardrail limits still apply; recharging does not automatically renew a plan.

Total storage and single-file limits follow current rights and the Files page. Plan storage is shared across the organization's workspaces; available storage add-ons increase capacity separately. Expiry or suspension can make storage read-only: uploads stop, while eligible downloads and deletion remain available. Confirm active rights before relying on renewal, added capacity or restored writes; a payment redirect alone is not confirmation.

Agent Cloud and Creative Studio resources

In Product subscriptions, choose Agent for cloud computing resources. Agent Cloud and Creative Studio share one 7-day trial starting at the first cloud activation. Viewing prices does not start it, and switching entrances does not create another trial. After expiry, an active subscription is required to continue cloud execution.

An active subscription provides seats, CPU, memory, cloud disk and included outbound traffic. Team resources are organization totals shared by Agent and Creative Studio, rather than a full copy for every member. There is no cumulative runtime-hour limit during the subscription, but concurrent resource limits and each task's maximum runtime still apply. Check current plan specifications and prices before purchase.

Idle interactive environments suspend after 15 minutes; active tasks continue. Stopping compute releases CPU and memory after shutdown is confirmed, while saved files continue to occupy organization storage. Expiry stops execution; instance databases follow the 7-day retention policy. File storage uses your remaining active entitlements and becomes read-only when usage exceeds them; renew or free space to continue writing.

Model generation is billed separately. Project files and creative assets share the included organization storage; storage add-ons increase the same pool. Use included outbound traffic first; excess costs ¥1/GB from the organization balance. Monthly allowances do not roll over; the shared trial includes 5 GB. A cloud resource subscription does not itself add ModelMix daily points.

View cloud plans →
BILLING

Usage, available capacity and settlement

Members and workspaces in an organization share its wallet. Available capacity can differ from its balance because running requests, pending charges and refund holds occupy capacity. Keys, workspaces and guardrails may also have their own budgets; recharging does not raise those limits. See Plans for daily points and wallet fallback.

A small positive balance or remaining budget can still allow one final request. Its actual charge can make the balance negative or exceed the budget. Exhausted balances or budgets stop new paid calls. For 402, check balance, budgets and plan status. For 429, reduce concurrency and follow the retry guidance.

Generation can finish before billing. billing_status=pending or cost_is_provisional=true indicates a provisional charge; settled identifies the final cost. Keep x-request-id from the response header or the returned generation_id and inspect Activity for status and details. Reading the original request does not repeat inference. Wallet records and usage totals can update later.

http
GET /api/v1/billing
Authorization: Bearer mmk-...

GET /api/v1/activity/{generation_id}
Authorization: Bearer mmk-...

If a result or charge is awaiting verification, keep the original request and contact support. A missing final charge is not a reason to resubmit. Cancellation or interrupted delivery can still incur charges for usage already produced.

Recharge, fees and refunds

Open Subscriptions & balance → Recharge orders, preview the order, check the credit and total payable, then pay with an offered method. Currency follows the organization wallet, independently of page language. The current recharge platform fee is 0%; existing orders retain their saved quote. Use the amount displayed on your order. Creating an unpaid order or returning from checkout does not confirm credit; check the original order and funds ledger.

Owners or billing administrators can request unused-principal refunds from a paid recharge order or Refund records. Stay within the displayed refundable amount; submitted funds are held, and cancellation is available before processing where offered. Standard principal refunds exclude fees and promotional credit. Approval alone does not confirm receipt: follow the final refund status. Product subscription refunds are handled in Product subscriptions under that product's refund rules.

Recharge instructions → · Request a consumption invoice →

BYOK charges

With your own provider key, the provider bills your provider account directly and ModelMix may charge a separate regional service fee. Monthly allowances, allowance currencies and excess rates are configured separately for each operating region; the organization's policy is fixed on its first BYOK use in that UTC month. Service fees settle in wallet currency. If fallback to platform credentials is allowed, those requests use platform model prices.

include_byok_in_limit is off by default when creating or editing an API key. Enabling it counts BYOK usage valued at catalog prices toward the key limit, including earlier usage in its current UTC budget period. It does not charge the provider bill to your wallet again or guarantee a hard cap on the provider account. Finish active requests before changing it.

Check charges and wallet transactions

Confirm the organization and date range. Use Activity to check the model, request ID, status and final charge; Usage charges for consumption details; and Funds ledger for credit, debits and refunds. Running requests and provisional charges may not yet appear in settled records. Request counts are not the same as wallet debit counts.

Organization financial records require the relevant billing permissions. Keep filters and currency with exports and do not add amounts in different currencies. For discrepancies, provide support with the request, order or refund ID, time and displayed error.

Open Funds ledger →

Request an invoice for settled consumption

Open Usage & records → Invoices for the intended organization. Owners or billing administrators can maintain invoice details and apply; billing viewers can read records. Invoices aggregate settled cash consumption from model usage, product subscriptions and resources in the same organization and currency. Recharge itself, gift credit, pending charges and unverified funds do not increase the eligible amount.

  1. Check the verified buyer identity. The title, subject type and enterprise tax identifier come from identity verification and cannot be replaced manually. Add the required enterprise address, phone, bank details and receipt email, then save. If a historical verification has no verified invoice identity, follow the page's verification instructions or contact support.
  2. Review Available to invoice and request all or part of it. Submitted applications reserve the corresponding consumption. You can withdraw before finance starts processing; rejected or withdrawn applications release the reserved amount.
  3. Track the application on this page and collect the document once it shows Issued. A consumption refund can require a credit note; check the original invoice and correction records for progress.
Open Invoices →
INTEGRATIONS

Keep the tools you already use

Use the integration guides for SDKs, coding agents, chat apps and frameworks with a custom OpenAI-compatible URL. Each guide includes configuration locations and official references. Select protocols, parameters and tools supported by both your client and model, then send a short message and check it in Activity.

Browse integration guides →

Responses and files

Use /v1/responses with input, tools, store, background and streaming. store controls whether a response is retained for later retrieval. background:true requires storage and cannot be combined with store:false. For continuation, save the returned response ID and pass previous_response_id with the creating workspace and key.

Responses also supports multi-turn WebSocket calls at /v1/responses. With store:false, connection-local continuation is not a durable record after disconnect. Strict zero-retention policies can prohibit stored responses, background jobs or files; check workspace privacy settings before retaining content.

SDK files use /v1/files with the purpose required by the task. Console Files and chat attachments use /api/v1/files; do not assume their file IDs are interchangeable. Keep the original workspace and credentials for subsequent access and check that the target model supports the file type.

Console files and chat attachments

Console Chat accepts up to 10 attachments, each at most 20 MiB. Chat attachments are private by default; account-session uploads explicitly choose visibility=private or visibility=workspace. The ordinary upload endpoint caps files at 512 MiB, subject to file settings, storage rights and model parsing limits. A stored file is not necessarily usable by every model.

Client and hosted tools

Declare client tools in the chosen protocol's tools field. Your application executes calls returned by the model and sends results back in that protocol. Tool support does not itself give the model access to your computer, files or external systems. Check endpoint support before requiring structured tool arguments.

Available ModelMix-hosted tools run on the platform, including modelmix:datetime for time, modelmix:web_fetch for web pages and modelmix:web_search for search. Check Key settings → Tools & plugins for permitted tools, call limits and charges. Tools and subsequent model turns can incur separate charges.

Provider-hosted search requires explicit support and pricing on the selected model. With Chat Completions, use an available ModelMix search tool; configure native search through a supported Responses, Messages or Google protocol. Client tool support does not imply every hosted search or other hosted tool is available.

Workspace administrators configure permitted hosted tools and call limits on the Tools page or at /api/v1/workspaces/{workspace_id}/tool-policy. Inference requests cannot override these limits.

API reference and request lookup

Inference and model discovery use /v1, or /v1beta for Google inference; accounts, workspaces and console features use /api/v1. The old /native/{provider} and /api/v1/chat/completions inference routes are no longer available. Update existing applications using the addresses in Quickstart.

http
POST /v1/chat/completions
POST /v1/responses
POST /v1/messages
POST /v1beta/models/{model}:generateContent
POST /v1/embeddings
POST /v1/rerank
POST /v1/images/generations
POST /v1/images/edits
POST /v1/audio/speech
POST /v1/audio/transcriptions
POST /v1/videos
POST /v1/files
POST /v1/batches
GET /v1/models?output_modalities=all&available_only=true

For a failed request, keep x-request-id, model ID, time and the error message, then search the request ID in Activity. For 400, check parameters and capabilities; 401, the key; 402, capacity and plan status; 403, verification and permissions; 404, path and model; and 429, concurrency and retry guidance. Keep full keys out of support tickets.

Organization reports, workspace departure and folders

Organization owners and admins can select an organization in Activity, Insights and Exports to include all its workspaces, including archived ones, and group by workspace_id. Cursors are bound to their scope; sessions remain separate across workspaces and keys. Organization reports require a personal session; ordinary members and API keys cannot access them.

Organization exports remain private to their creator. Organization access is rechecked during generation and download, and after a report query before results are returned. Activity, analytics, sessions and upstream attempts support CSV export.

http
POST /api/v1/organizations/{organization_id}/analytics/query
POST /api/v1/organizations/{organization_id}/report-exports
POST /api/v1/workspaces/{workspace_id}/leave
{"confirm_workspace_id":"workspace-id"}
POST /api/v1/workspaces/{workspace_id}/file-folders
{"name":"Reports","parent_id":null}
PATCH /api/v1/workspaces/{workspace_id}/file-folders/{folder_id}
{"parent_id":"parent-folder-id","expected_revision":1}
PATCH /api/v1/files/{file_id}
{"folder_id":"folder-id","expected_revision":1}

Members can leave from Workspace management. Personal and management keys are disabled and their service keys require administrator review. Owners must transfer ownership first; the last workspace administrator cannot leave. Files supports up to 200 shared folders with 8 levels of nesting, renaming, subtree moves and empty-folder deletion. Sibling names must be unique; folders cannot move into their descendants. Remove files and child folders before deletion. Moves preserve file IDs; revision conflicts require a refresh. Upload and inference obey workspace file settings and storage limits.

http
POST /api/v1/audio/tasks/{task_id}/content/save
POST /api/v1/videos/{task_id}/content/save
GET /api/v1/files/{file_id}/content

Once a successful speech or video task offers Save, you can save a private Files copy even with billing_status=pending, without generating or charging for inference again. Speech keeps WAV/MP3/FLAC up to 32 MiB (subject to the current limit shown on the page); video supports MP4 up to 64 MiB. A saved copy remains available after its source expires. Storage capacity, single-file limits and permissions still apply; retry saving the original task after a failure. Deleting a copy releases space, and you can save it again while the source remains available.

NOTIFICATIONS

Personal account notifications

Open Notifications in the console for account security events, low balance and workspace budget alerts. Choose alert thresholds, filter unread messages and mark a category as read. Notifications are retained for 90 days. Personal sessions are required; API and management keys cannot access this inbox.

Financial alerts use settled wallet charges, excluding in-flight and pending usage. Alerts may be delayed; check the current balance and charges. When email is configured, subscribe to new reminders at your verified address; financial details remain in the console. Unsubscribing cancels queued mail. Failed deliveries can be retried from the inbox. If a reminder does not arrive, check spam and your in-app notifications. Personal notifications do not currently offer SMS reminders.

Generation receipt Webhooks are a separate workspace feature, disabled by default. Administrators configure GET/PATCH /api/v1/workspaces/{workspace_id}/generation-webhook with a personal session; append /deliveries to list deliveries. They send settled status, usage and wallet-cost metadata. Set include_media_ready=true for settled media.ready events containing relative task/download paths requiring the original key, without prompts, model output, file content or supplier signed URLs. Receivers must verify HMAC signatures and deduplicate event IDs; retries can be duplicated or out of order. Webhooks supplement polling, do not guarantee supplier video availability, and remain separate from personal notification subscriptions.

Shared guardrail budgets have a separate subscription and a 1–100% alert threshold for daily, weekly, monthly and lifetime limits. Organization policies notify organization administrators; workspace policies notify workspace administrators. Your favorites and readable private/shared collections can also receive retirement and price alerts without exposing collection names or notes. Personal favorites and the catalogue remain accessible without workspace membership.

Model alerts match exact references, preset/favorite latest aliases and key wildcard rules saved before the event. Aliases use the publication catalogue; matching rules do not indicate actual usage. Retirement and price subscriptions are independent. Turning off a balance, workspace budget, guardrail budget or model alert cancels its queued mail; retries recheck the subscription and current access.

Workspace administrators can email an invitation or replace it with a new invitation and email, revoking the previous token. The recipient signs in with the invited address and pastes the seven-day token in Workspace management.

HTTP
GET /api/v1/accounts/notifications?category=billing&unread_only=true
Authorization: Bearer urs-your-session

POST /api/v1/accounts/notifications/read
Authorization: Bearer urs-your-session
Content-Type: application/json

{"ids":["123"]}
BACKGROUND EXPORTS

Export a complete query

Apply filters in Request activity or Usage insights, choose Export full query, then open Exports to follow progress, cancel or download CSV. Request activity, analytics, sessions and upstream attempts are supported. Partial files are never offered.

Exports reflect data at processing time and may exclude newer records. Create another export when you need updated records. Files require the owner's personal session and current workspace membership and expire after 24 hours. Limits are 100,000 rows or 16 MiB per file, two active jobs and twenty new jobs per account per day. Narrow the query when a limit is exceeded.

HTTP
POST /api/v1/report-exports
Authorization: Bearer urs-your-session
X-ModelMix-Workspace: ws-your-workspace
Content-Type: application/json

{"kind":"analytics","query":{"dimensions":["model"],"metrics":["request_count","wallet_cost"]},"request_id":"export-operation-unique-001"}
KEY GOVERNANCE

Key lifetime and existing credential governance

Set account and workspace lifetime ceilings in API Keys or Management Keys. The shorter ceiling wins. Organization administrators manage the account layer; workspace administrators manage their workspace layer. Policy saves apply to newly issued and rotated credentials.

Select up to 100 existing keys to preview the current ceiling or batch disable. A preview lasts five minutes; applying it rechecks the personal session, administrator access, policies and selected credentials. Changes require a fresh preview. Ceilings run from secret issuance and never extend existing deadlines; unknown issuance requires rotation. Tightening retires grace secrets while admitted requests can finish settling.

Notifications flag soon-to-expire and recently expired keys, with optional email reminders in Notification preferences. Rotate and update application settings before expiry; keys are not rotated automatically.

In Organization management → Key governance, organization administrators can review key risks across active workspaces, filter by expiry, review and lifetime compliance, and create one reviewed preview for keys from multiple workspaces. Applying a batch requires current administrator access in every selected workspace; a refreshed console can recover an unfinished preview or completed receipt. The privacy impact report combines account, workspace, key and guardrail restrictions and evaluates static endpoint eligibility without saving policy or invoking providers.

HTTP
POST /api/v1/workspaces/{workspace_id}/key-lifecycle/preview
Authorization: Bearer urs-your-session
X-ModelMix-Workspace: ws-your-workspace
Content-Type: application/json

{"operation":"enforce","key_ids":["key-your-key"]}

POST /api/v1/workspaces/{workspace_id}/key-lifecycle/apply
{"preview_id":"klp-returned-by-preview"}

GET /api/v1/organizations/{organization_id}/keys?status=noncompliant
POST /api/v1/organizations/{organization_id}/keys/preview
POST /api/v1/organizations/{organization_id}/keys/privacy-impact

Protect your account and keys

Enable an authenticator, keep recovery codes private and review sign-in sessions. Create separate inference keys for applications with suitable model permissions, budgets and expiry. Keep keys in protected application configuration, away from public pages, repositories, screenshots and messages.

Full secrets are shown when created or rotated. Disable or rotate a leaked key immediately and update your application. Signing out of the website does not disable API keys. Workspace administrators can also configure key lifetime and privacy policies.

Account security → · Key lifecycle →

Read the full User Agreement · Read the full Privacy Policy

SERVICE TERMS

Provider terms flow through

You are responsible for honoring each provider's pricing, regional restrictions, data obligations, and applicable tax or invoicing requirements.