开始使用 ModelMix
从注册账户到第一次对话,按下面的顺序操作即可。每章都说明入口、操作步骤和完成标志;使用网页聊天无需编程。
开始前准备
- 可正常接收验证码的邮箱或手机号。
- 本人的身份证件,以及可使用摄像头的手机或电脑;企业用户还需准备企业登记资料。
- 如需充值或购买套餐,按需准备页面支持的支付方式。登录和支付方式取决于账户所属区域及已开通服务,以页面实际显示为准。
注册后会自动创建个人组织和默认工作区。实名认证和钱包归组织所有,密钥、文件与项目配置归工作区所有;认证或充值前请先确认当前组织。注册时会根据 IP 推荐运营区域,你可以在创建账户前选择;注册后区域不可修改。中国大陆区使用人民币,其余区域使用美元。切换网页语言不会改变区域或币种。 查看功能与概念解析 →
付费使用前,请确认钱包可用额度或已生效 ModelMix 套餐的每日点数。套餐与钱包分开管理:点数按上海时间零点重置,点数不足时使用钱包回退的开关默认关闭。 查看套餐和点数说明 →
注册账户
方式一:邮箱注册
切换到创建账户
选择“邮箱”,点击登录表单下方的“创建账户”。
验证邮箱
输入邮箱,点击“获取验证码”,从邮件中取出 6 位验证码,在页面提示的有效期内填写。未收到时检查垃圾邮件;重新发送后请使用最新验证码。
设置密码并创建账户
设置 15–256 个字符的密码,避免常见或已泄露密码。阅读《用户协议》和《隐私政策》,主动勾选同意后点击“创建账户”。系统会自动创建个人组织和默认工作区,名称可在登录后修改。
方式二:手机号注册
选择手机号并获取验证码
选择“手机号”和“验证码登录”。中国区可直接填写大陆 11 位手机号;国际区请填写带 + 国家码的完整号码。点击“获取验证码”,填写 6 位短信验证码。
登录并自动创建账户
阅读《用户协议》和《隐私政策》并勾选同意后,点击“安全登录”。开放注册时,未注册的手机号会自动创建账户,已注册号码直接登录原账户。首次使用无需设置密码,之后可在“账户设置 → 登录与安全”设置。
进入控制台,或看到当前账户所需的安全设置提示。如要求绑定认证器,先按提示完成,再继续组织实名认证。注册成功不代表已完成实名认证。
如提示注册关闭或验证码服务不可用,请联系平台支持。国际区配置完成后也可能显示 Google / GitHub;已有同邮箱账户请使用原登录方式。
下一步:登录控制台 →登录控制台
选择账户对应的登录方式
邮箱用户填写邮箱和密码,也可切换到已开放的“验证码登录”;手机号用户默认使用短信验证码,设置过密码后也可切换到“密码登录”。填写后点击“安全登录”。
完成 MFA 安全验证
如出现二次验证,输入认证器 App 的动态验证码或尚未使用的恢复码。MFA 是额外的安全验证,与邮箱、短信验证码不同。如组织要求首次绑定,请按页面设置认证器,妥善保存恢复码后重新登录。
确认组织与工作区
查看控制台顶部的组织与工作区切换器,选择本次要使用的项目。钱包属于组织,同一组织内切换工作区不会得到另一份独立余额。
控制台显示预期的组织和工作区;组织未认证时,仍会显示实名认证提示。
忘记密码怎么办?
在邮箱或手机号的“密码登录”表单点击“忘记密码?”,按邮件重置链接或短信找回流程设置新的 15–256 字符密码,再重新登录。已启用 MFA 时,还需动态验证码或恢复码。密码重置会使旧会话退出;尚未设置密码的手机号账户可先用短信登录,再到“账户设置 → 登录与安全”设置密码。
“网关密钥”适用于已经持有密钥的用户,访问范围由该密钥决定。实名认证、充值和账户设置请使用个人账户登录。
下一步:实名认证 →完成实名认证
中国区和国际区都要求组织认证后才能发起充值和使用模型。认证属于当前组织,由其成员和工作区共用;如无提交权限,请联系组织所有者完成。
确认组织并选择认证类型
选择“个人实名认证”或“企业实名认证”。中国区个人认证需本人姓名和身份证;企业认证还需企业名称、统一社会信用代码和法人身份资料,由法人本人完成人脸核验。国际区个人认证使用护照,企业在经办人完成 eKYC 后,还需人工复核登记信息及授权关系。
选择认证设备
电脑端可选择“手机扫码认证”并点击“生成认证二维码”,用手机相机扫码后,在手机填写实名资料、确认授权并核验,无需重新登录;保留电脑页面等待同步。也可选择“使用本机摄像头”。手机直接操作时,使用当前设备并允许摄像头访问。
确认授权并完成核验
阅读授权说明,确认同意后,在实际核验设备上点击“开始认证”,按阿里云页面完成证件及人脸核验。认证链接仅由认证本人使用;摄像头无法打开时,请用 Safari / Chrome 打开并允许访问。
返回并核对结果
服务商流程结束后返回 ModelMix;电脑页面会同步结果,必要时点击“刷新认证状态”。跳转返回并不代表认证通过。显示“人工复核”时,保留认证申请编号并联系平台支持。
| 状态 | 应如何处理 |
|---|---|
| 未认证 | 选择认证类型并发起认证。 |
| 正在发起 / 核验中 | 继续当前申请,完成后刷新状态,避免重复发起。 |
| 人工复核 | 提供认证申请编号,按平台支持要求补充核验资料。 |
| 已认证 | 当前组织可继续充值和使用模型,仍需满足余额与权限要求。 |
| 未通过 / 已过期 / 已撤销 | 查看结果并处理原因后重新申请;认证撤销也会阻止旧密钥发起新调用。 |
目标组织的认证状态显示“已认证”。如提示认证服务不可用或尚未配置,请联系平台支持处理。
充值与到账确认
请使用组织所有者或具备 Billing Admin(财务管理)权限的个人账户,并先完成该组织实名认证。Billing Viewer(财务只读)可查看记录;看不到充值按钮时,请联系组织所有者检查财务权限。
充值增加钱包余额,不会购买或续订套餐。已有生效套餐时,先检查剩余点数和钱包回退开关,再决定是否充值。 套餐与每日点数 →
确认充值到哪个钱包
核对财务页面显示的组织,点击“充值”,按页面币种输入希望到账的额度,金额需在页面允许范围内。
预览金额与费用
点击“预览订单”,系统根据本次报价生成待付款订单。前往收银台前,核对到账额度、平台手续费和应付总额。报价过期时重新预览;费率和限额以本次页面报价为准。
选择支付方式
从页面列出的方式中选择渠道,点击“创建或继续收银”。按提示扫码、前往安全收银台或在线网关支付。仅显示当前区域已配置的方式;列表为空表示当前没有可用支付渠道。
完成支付并确认到账
在页面提示的截止时间前支付,返回原订单,点击“刷新支付状态”或“刷新记录”。核对订单已付款,且该组织余额或资金流水中出现充值入账。打开收银台、扫码或浏览器返回都不等于支付成功。
处理已付款但未到账
打开原订单“查看详情”,如有“查询原支付”则点击后刷新。如仍显示处理中或需人工核查,请向平台支持提供订单号、付款时间和渠道交易号;原支付未确认前,避免另建订单重复付款。
到账额度 + 平台手续费 = 应付总额
订单显示已付款,并可在目标组织的钱包记录中核对到账。设置密钥预算不会增加钱包余额。
如何申请退款?
进入已付款订单“查看详情 → 申请退款”,或进入“退款记录”发起申请。选择符合条件的订单,在“当前可退”范围内填写金额和原因后提交;可退的未消费本金会在审核期间冻结。申请提交或审批通过不等于退款到账,请继续查看最终状态。标准未用本金退款不包含手续费和赠送余额。
开始对话或接入应用
使用网页聊天
打开聊天并选择模型
进入“聊天”,确认工作区并选择可用模型。网页聊天使用当前登录账户,无需在聊天界面粘贴 API 密钥。 进入控制台 ↗
发送简短测试消息
例如输入“请用一句话介绍你自己”,发送后等待回复。模型请求可能产生费用,请先核对所选模型的价格。
查看请求与费用
到“请求记录”查看结果,再到“消费账单”查看当前工作区费用。回答完成时费用可能仍为待结算,刷新后核对最终入账费用;同一组织下的工作区共享钱包。
使用 API 密钥接入应用
在目标工作区创建密钥
进入“API 密钥 → 创建密钥”,个人测试可选择个人推理密钥,填写名称,设置预算、有效期和必要的模型限制。预算是消费上限,不是充值。 打开 API 密钥 ↗
保存密钥并配置应用
完整密钥只在创建或轮换时显示,请立即妥善保存;丢失后需轮换。应用中填写 ModelMix 接口地址、mmk- 开头的推理密钥,以及当前目录中的完整模型 ID。urm- 开头的管理密钥不能调用模型。
WorkBuddy / 扣子配置说明 → · SDK 快速开始 → · AI 助手 → · 创意工作台 →
网页或应用收到模型回复,且能在目标工作区查看对应请求。调用失败时,可按下方常见问题检查权限、认证、余额和预算。
密码、MFA 与登录会话
设置或修改密码
无密码的手机号账户可在密码设置表单中重新获取短信验证码,设置 15–256 字符密码。已有密码时,填写当前密码、新密码及确认密码,按提示完成 MFA。设置、修改或重置成功后旧会话失效,需要重新登录。
启用认证器并保存恢复码
按 MFA 设置表单,用认证器 App 扫描绑定二维码,填写当前动态验证码并妥善保存恢复码。每个恢复码只能使用一次。如提示先设置密码,请完成后重新登录,再继续绑定。
检查会话并退出登录
打开“会话管理”查看活跃会话与近期安全事件,撤销不认识的会话,或退出其他会话。使用公共设备后点击控制台“退出登录”。如 API 密钥泄露,还需单独到“API 密钥”轮换或停用。
账户设置和会话管理显示预期的 MFA 与会话状态,恢复码已妥善保存。公开截图或工单中不要包含密码、验证码、完整 API 密钥或身份证件。
常见问题与求助
能登录,为什么不能充值或使用模型?
先检查当前组织是否“已认证”。登录验证的是账户联系方式,实名认证核验的是组织主体;如有强制 MFA 设置提示,也需完成。已认证后还需满足余额、预算和模型权限。
收不到验证码怎么办?
核对邮箱、手机号码和国家码,检查垃圾邮件,并查看页面重发倒计时。冷却结束后再获取,使用有效期内的最新验证码;如提示服务不可用或操作频繁,请按重试时间等待或联系平台支持。
实名认证摄像头或二维码无法使用?
允许摄像头访问,并使用 Safari / Chrome。电脑无摄像头可改用手机扫码认证;链接过期后重新生成二维码,按手机自己的核验流程完成,不要把电脑生成的服务商链接转到另一设备。链接仅由认证本人打开。
支付渠道显示成功,余额却没增加?
确认查看的是目标组织下的原订单,刷新或查询原支付,保存订单号和渠道交易号。处理中、人工核查状态还需继续确认,长时间未解决时联系平台支持,避免重复付款。
为什么余额与可用额度不同,充值后仍可能调用失败?
可用额度还会考虑进行中的请求、待结算及冻结资金;密钥和工作区还可能有独立预算、有效期与模型限制。订阅用户还需检查剩余点数、套餐状态和钱包回退开关;充值不会自动续订套餐或提高密钥预算,切换语言也不会改变钱包币种。
应用报 401、402、403、404 或 429 怎么处理?
401 先检查密钥和接口地址;402 检查钱包可用额度与预算,订阅用户还需检查套餐状态、剩余点数和钱包回退开关;403 检查实名认证和权限;404 检查路径与完整模型 ID;429 降低请求频率或并发并按返回提示重试。具体原因以实际错误信息为准。
为什么设置密码后原来的设备退出了?
设置、修改或重置密码会撤销旧会话。请使用更新后的登录凭据及已启用的 MFA 重新登录;API 密钥有独立生命周期,需要时另行检查。
提交问题给平台支持
确认当前组织,选择问题分类,描述操作过程,尽量填写关联的请求、充值订单或退款编号,并注明发生时间及所在时区、页面错误提示。如支持人员需要截图,请通过其指定渠道提供脱敏截图。提交后在同一工单查看回复。无法登录时,请使用平台提供的支持联系方式。
不要在工单中填写密码、验证码、恢复码、完整密钥或证件资料;身份核验补充资料请按平台支持指定的受限渠道提交。
通过统一接口
接入多种模型。
AIDMX 是兼容 OpenAI 的网关,提供供应商感知路由、自动回退、用量控制和钱包异步结算。为应用配置 AIDMX 基础地址和推理密钥,并核对所选模型与端点的能力。
按主题阅读
https://stg-api.aidmx.net/v1OpenAI 兼容客户端的 Base URL 以 /v1 结尾,模型目录使用同一地址下的 /models。不要填写 /api/v1,也不要重复添加 /chat/completions。/api/v1 用于账户、工作区及控制台功能。模型调用需要 mmk- 推理密钥,不能使用网站登录密码或管理密钥。
| 客户端 | Base URL | 请求路径 |
|---|---|---|
| OpenAI SDK | https://stg-api.aidmx.net/v1 | /chat/completions · /responses |
| Anthropic SDK | https://stg-api.aidmx.net | /v1/messages |
| Google Gen AI SDK | https://stg-api.aidmx.net | /v1beta/models/…:generateContent |
Google Gen AI SDK 的 API version 选择 v1beta。各协议均填写 ModelMix 目录中的完整模型 ID;同一模型支持哪些协议、工具与输入类型,以模型详情为准。
安装 SDK
pip install openai先登录控制台,为当前组织完成身份验证,确认钱包余额或已生效的套餐点数,再创建工作区推理 Key。组织和工作区决定账户区域与可用模型,网页语言不会改变它们。用该 Key 查询 /v1/models?task_type=chat&available_only=true,选择已定价、尚未退役的聊天模型;目录配置不保证供应商实时可用。
初次使用:了解用户、组织、工作区和密钥 →发送第一个请求
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)功能与概念解析
了解谁在使用系统、资源归属哪里、应用该用哪种密钥,以及费用如何控制。
举例:团队的客服应用你以用户身份登录,加入公司的组织。在组织内建立“测试”和“生产”两个工作区,分别管理密钥、文件和配置,共享组织钱包。为客服应用配置对应工作区的 API Key;要使用自己的供应商账户时,再在该工作区配置 BYOK 凭据。
用户与资源归属
- 用户 / 账户(User)
代表登录系统的个人身份,拥有自己的资料、安全设置和登录会话。一个用户可以加入多个组织和工作区,在每个组织、工作区的权限由对应的成员身份和角色决定。
- 组织(Organization)
资源和账务的归属主体,可以用于个人或团队。组织包含工作区,统一管理钱包、身份验证和记账币种。个人注册也会创建个人组织和默认工作区,个人开发者与团队使用同一套结构。
- 工作区(Workspace)
组织内的项目或环境边界,例如“测试环境”和“生产环境”。每个工作区分别管理 API Key、BYOK 凭据、文件、预设和策略。同一组织内的工作区共享组织钱包,可以设置各自的消费预算。
- 成员 / 角色(Member / Role)
成员身份表示用户已加入某个组织或工作区;角色决定可以执行哪些操作。组织所有者、组织管理员负责组织治理,工作区管理员负责本工作区的资源管理。财务权限另行授权,能访问工作区不代表可以操作组织财务。
密钥与应用身份
- API Key / 推理密钥
由 ModelMix 发放、供 SDK 或应用调用模型的凭据,在“API 密钥”中创建。推理密钥使用 mmk- 前缀,绑定工作区,可限制模型、供应商、消费额度、请求速率和有效期。接入应用时,api_key 填写这把密钥。
- 个人密钥(Personal Key)
绑定个人身份及当前工作区成员关系的一种推理密钥,适合个人开发和调试。退出工作区或个人账户被停用后,该密钥不能继续使用。
- 自有密钥(BYOK)
BYOK 是 Bring Your Own Key 的缩写,指在工作区配置你自己的模型供应商密钥。应用仍使用 ModelMix 推理密钥,网关在符合条件的请求中使用该供应商凭据。模型费用由供应商向你的供应商账户收取,ModelMix 可能按所属区域的 BYOK 政策收取服务费;允许回退且实际使用平台凭据时,按平台推理计费。
- 服务账户 / 服务密钥
服务账户是组织所有的应用身份,可被授权使用指定工作区;服务密钥是其调用模型的推理凭据,适合服务器和定时任务。账户及工作区授权由管理员管理,应用通过服务身份运行。
- 管理密钥(Management Key)
用于自动化管理某个工作区的凭据,使用 urm- 前缀。通过明确授权,可管理推理密钥、BYOK 凭据、护栏或读取报表。管理密钥不能调用模型、操作钱包或管理其他工作区,读取和写入权限分别授予。
余额与消费控制
- 钱包 / 余额(Wallet / Balance)
归组织所有的资金,用于支付平台推理费及适用的服务费。新请求可用额度需扣除在途预占、待结算费用及其他资金预留。正余额不足标准预占时,组织没有其他在途请求即可放行最后一笔;实际结算后余额可以为负。扣除待结算费用后余额不为正,则停止新收费请求。充值先补欠费,再恢复可用额度。钱包币种由组织计费配置确定。
- 预算 / Key 额度(Budget / Limit)
工作区或密钥的消费额度,可按每日、每周、每月或累计设置。设置预算不会增加钱包余额。Key、工作区、护栏和 Agent 推理预算分别计入实际支出、在途预占和待结算费用;正剩余额度不足一次预占时,仅在该预算范围没有其他付费请求在途时放行最后一笔,实际费用允许超出预算。预算耗尽后停止新的付费调用。开启相应选项后,BYOK 用量也可计入 Key 额度。
- 在途用量 / 异步结算(Settlement)
进行中的请求会占用部分钱包和预算可用额度。生成后按实际用量计费,费用可能短暂处于待结算状态;重新查询原请求可获取 settled 的最终费用。收到回答不代表账单和用量报表已更新完成。
模型与请求行为
- 模型(Model)
应用通过 model 字段选择的 AI 能力,通常以 author/model 这样的模型 ID 标识。不同模型支持的任务、参数、上下文长度和价格不同,选择前应查看当前工作区密钥可访问的模型目录。
- 供应商 / 端点(Provider / Endpoint)
供应商提供模型服务;端点是具体配置的一条模型访问通道。同一模型可能有多个供应商或端点,其能力、可用性和隐私声明可能不同。目录展示配置情况,实时可用性仍取决于供应商。
- 路由 / 回退(Routing / Fallback)
路由为请求选择符合条件的端点,自动模型路由还可选择模型;回退在初始通道失败时尝试符合条件的备选通道或模型。路由和回退仍需遵守模型权限、预算及隐私策略。
- 预设(Preset)
保存并复用的一组请求配置,例如模型、参数和路由偏好,帮助应用保持一致的调用设置。使用预设仍需要有效的推理密钥及所选模型的访问权限。
- 护栏(Guardrails)
限制请求行为的策略,可约束模型或供应商访问、敏感内容和共享消费额度。组织策略可以应用到工作区成员及密钥,请求需要满足所有适用的策略。
- 隐私 / 零留存(ZDR)
隐私策略控制数据处理通道和日志行为。ZDR 是 Zero Data Retention(零数据留存),用于筛选声明满足供应商留存要求的端点。显式保存的聊天、文件和账务记录按各自规则保留,账户区域本身不保证数据的实际处理地点。
了解概念后,可以继续阅读具体用法: API Key 鉴权 · 计费与 BYOK · 供应商路由 · 护栏 · 隐私控制
把 ModelMix 接到常用工具
先准备接口地址、推理密钥和模型 ID,再按对应工具的步骤填写。下面的流程示意和参数速查可配合文字步骤使用。
准备一个专用推理 Key
完成组织认证并确认钱包额度或生效套餐点数后,在当前工作区的“API 密钥 → 创建密钥”中创建 mmk- 开头的普通推理 Key,可自行命名为 WorkBuddy 等工具名称并设置预算。各工具使用同一套密钥创建流程。不要使用 urm- 管理 Key 或网站登录凭据。 打开 API 密钥 →
确认地址和可用模型
使用下方地址,并用同一把 Key 查询模型列表。复制一个已定价、未退役的聊天模型 id;需要执行工具时,核对该模型端点的工具调用能力。示例中的 MODEL_ID_FROM_CATALOG 需要替换。
https://stg-api.aidmx.net/v1export MODELMIX_API_BASE="https://stg-api.aidmx.net/v1"
# 在本机设置 MODELMIX_API_KEY 为你的推理 Key,再查询模型:
curl --fail-with-body "$MODELMIX_API_BASE/models?task_type=chat&available_only=true" \
-H "Authorization: Bearer $MODELMIX_API_KEY"接口地址以 /v1 结尾,请使用本页显示的地址。扣子云端调用需要公网可达的 HTTPS 地址;localhost、127.0.0.1 和内网地址仅适用于能访问它们的本机环境。向第三方工具保存 Key 即授权它使用该 Key 调用模型;请只在其密钥设置中填写。
以下示例适用于支持自定义 OpenAI 聊天接口的工具版本,菜单名称和开放权限以工具实际页面为准。
WorkBuddy 配置
使用自定义供应商接入 ModelMix,按下表填写。
在 ModelMix 的“API 密钥 → 创建密钥”中创建普通推理 Key;无需专用密钥类型。已有密钥也可在“更多操作 → 接入 WorkBuddy”中校验并复制参数或下载填写指南;该操作不会自动修改 WorkBuddy 客户端。已有密钥明文不能重新读取,请使用创建时保存的密钥。
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 名称 | ModelMix | 用于识别,可自行命名 |
| 供应商 | Custom / 自定义 | 使用兼容 OpenAI 的聊天接口 |
| Base URL / 接口地址 | https://stg-api.aidmx.net/v1 | 保留 /v1;不要再加 /chat/completions |
| API Key | mmk-… | 替换为你的推理 Key,仅填 Key 本身 |
| 模型 ID / 模型名称 | MODEL_ID_FROM_CATALOG | 替换为当前 Key 查询 /models 返回的完整 id |
打开模型设置
进入“设置 → 模型”,添加自定义模型,供应商选择 Custom / 自定义。
填写参数并保存
粘贴 Base URL、mmk- 推理 Key 和完整模型 ID。“自定义协议”保持关闭,让 WorkBuddy 自动补全 /chat/completions。工具调用、图片输入和思考选项按实际端点能力设置。
在对话中选中模型
保存后,在对话的模型选择器中选中刚添加的模型,再发起测试。
新建对话,明确选择刚添加的 ModelMix 模型,发送“请只回复:连接成功”。收到正常回复后,在 ModelMix 控制台的“请求记录”核对模型与本次请求;费用可能稍后结算。需要文件操作时,再用一个临时测试文件验证工具调用。
官方参考:WorkBuddy 模型配置 ↗
扣子网页端配置
在 coze.cn 的 Agent 模型菜单选择“添加自定义模型 → 自定义接入”,使用下列配置。按当前官方说明,个人账号需进阶版及以上;企业权限与 Agent 类型也会影响入口是否可见。
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 名称 | ModelMix | 用于识别,可自行命名 |
| 模型协议 | Chat API | 使用兼容 OpenAI 的聊天接口 |
| API URL | https://stg-api.aidmx.net/v1 | 保留 /v1;不要再加 /chat/completions |
| API Key | mmk-… | 替换为你的推理 Key,仅填 Key 本身 |
| 模型 ID / 模型名称 | MODEL_ID_FROM_CATALOG | 替换为当前 Key 查询 /models 返回的完整 id |
选择自定义接入
登录扣子网页端,打开目标 Agent 的对话与模型菜单,进入添加自定义模型;选择“自定义接入”。
添加并选择模型
名称可写 ModelMix;模型 ID 填查询结果中的完整 id;协议选 Chat API,API URL 和 Key 按上表填写。输入与回复长度不要超过该 ModelMix 端点公布的上限,图片理解按能力开启。添加后在当前 Agent 中选中它。
新建对话,明确选择刚添加的 ModelMix 模型,发送“请只回复:连接成功”。收到正常回复后,在 ModelMix 控制台的“请求记录”核对模型与本次请求;费用可能稍后结算。需要文件操作时,再用一个临时测试文件验证工具调用。
在扣子编程的工作流中使用
code.coze.cn 的低代码模型接入使用单独的企业权限。符合条件的组织管理员可进入“企业组织管理 → 模型接入 → 自定义模型”,配置同一地址、模型 ID 和 Authorization 鉴权,再为工作空间授权。普通账号可按工作流 HTTP 节点能力调用完整的 /chat/completions 地址,Header 使用 Authorization: Bearer 加推理 Key;这只用于该节点,不会替换 Agent 的默认模型。
官方参考:扣子模型设置 ↗
扣子客户端配置
这里指 macOS / Windows 桌面端。使用与网页端相同的三项接入参数,协议选择 Chat API。
https://stg-api.aidmx.net/v1登录并找到模型入口
安装官方桌面端,登录扣子账号;打开目标 Agent 的对话,展开模型列表,选择添加自定义模型。
保存 ModelMix 配置
选择自定义接入,填写 ModelMix 名称、完整模型 ID、Chat API、上方 API URL 和你的 mmk- Key。能力与长度限制参照端点设置。 查看完整字段表 →
切换后验证
添加后在对话中明确选中该模型。看不到入口时,先确认客户端版本、套餐和 Agent 类型,再对照网页端检查。移动 App 暂不支持添加和管理自定义模型。
新建对话,明确选择刚添加的 ModelMix 模型,发送“请只回复:连接成功”。收到正常回复后,在 ModelMix 控制台的“请求记录”核对模型与本次请求;费用可能稍后结算。需要文件操作时,再用一个临时测试文件验证工具调用。
官方参考:扣子模型设置(网页端与桌面端) ↗
配置后无法使用时,按这里排查
| 现象 | 检查方法 |
|---|---|
| 401 / 鉴权失败 | 确认使用 mmk- 推理 Key,检查是否过期或停用。客户端 API Key 输入框只填 Key,手工 HTTP Header 则填 Authorization: Bearer mmk-…。 |
| 402 / 可用额度不足 | 检查钱包可用余额、Key 预算及账单状态;订阅用户还需检查套餐是否生效、剩余点数和钱包回退开关。充值不会自动续费套餐。 |
| 403 / 无权限 | 检查组织实名认证、Key 的模型白名单与区域限制;扣子入口不可见时另查其套餐、Agent 类型和企业权限。 |
| 404 / 地址或模型不存在 | Base URL 保留 /v1,不重复添加 /chat/completions;模型 ID 必须与同一 Key 查询结果一致。 |
| 429 / 请求过多 | 降低并发并按 Retry-After 等待,检查 Key 与供应商限流;避免让多个工具同时自动重试。 |
| 能聊天,不能调用工具或看图 | 检查所选端点的 tools / 图片输入能力、客户端开关与请求参数。文本回复成功不代表已支持所有 Agent 能力。 |
| 超时或没有流式输出 | 先在本机做下方 SSE 测试,再检查代理是否缓冲 text/event-stream、网络可达性和供应商状态。扣子云端无法访问你的 localhost。 |
验证流式接口
在本机设置 MODELMIX_API_BASE、MODELMIX_API_KEY,并将下方模型占位值替换为实际 id 后执行。它会发起一次按用量计费的请求;成功时应持续输出 data: 事件并以 [DONE] 结束。
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}'仍有问题时,记录时间、工具版本、模型 ID、HTTP 状态码和响应中的请求 ID,再联系支持。截图、日志和录屏中请遮住密钥。停用或轮换专用 Key 后,记得同步更新工具配置。
模型目录会展示平台计划退役的时间、公开说明和建议替代模型。计划发布后,到期停止接受该模型的新请求,自动路由和响应缓存同样受限;已提交任务仍可恢复和下载。系统不会自动将请求改发替代模型,请先验证能力、价格与权限,再明确修改配置。
模型发现模型详情、比较与费用估算
公开模型目录提供独立详情、最多四模型比较及按任务/能力分类。筛选与模型选择可通过页面链接分享。控制台中的详情与比较直接使用当前连接的网关。
公开目录展示当前区域开放的模型能力和售价。supported_parameters 是模型参数的汇总,具体支持情况以端点的 parameter_contract 为准。组合筛选要求同一个端点同时满足参数、供应商、ZDR 和上下文条件。目录展示不保证供应商实时可用。
估算按一次请求计算当前区域公布的模型售价,包含请求费、缓存、音频、图片和长上下文档位。以返回的 currency 为准,可能是 USD 或 CNY;不同币种不能直接比较或相加,钱包结算还可能涉及换算。媒体采用字符、秒或分辨率费率,重排采用对应的 Token 或搜索单位。缓存与音频 Token 包含在输入总数内,其他任务的计费单位不参与该端点计算。BYOK、工具、税费、重试及账户策略不包含在估算中。
停用、未定价、超出用量或上下文上限的端点不会返回费用。按 Token 计费的视频因用量无法预知而不提供预估;零价端点明确显示为零。目录快照摘要用于识别比较时的配置,不构成锁价。分类不是质量排名,尚无真实性能榜单;用户自定义集合可在控制台模型页保存和管理。
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}}保存和共享模型集合
控制台模型页中的自定义集合支持名称、说明、有序模型列表和逐模型备注,可批量加入目录模型、导入已有收藏、调整顺序,以及直接比较或试用所选模型。需要个人登录会话和当前有效工作区;推理 Key 和管理 Key 不能访问。
私人集合仅本人可见,包括工作区管理员也不能读取他人的私人集合。共享集合对当前工作区成员可见,由管理员编辑或删除;只有仍具备管理员权限的创建者可以改变可见范围。成员可复制为自己的私人集合,副本不随原集合撤回共享或删除而消失。不存在匿名或跨工作区分享。
每人每工作区最多 50 个私人集合,每工作区最多 50 个共享集合,每个集合最多 100 个不同模型。名称 80 字、说明 1,000 字、单条备注 500 字,集合内容最多 128 KiB。API 修改、复制和删除需携带当前 expected_revision;发生版本冲突时先刷新核对。
新条目必须来自当前区域目录。已保存但从目录退役的条目会保留并显示不可用,仍可改备注、移除或复制。重新加入已移除的退役条目会被拒绝。集合本身不授予模型调用权限,也不触发付费请求。保存超时请先刷新核对,避免重复提交;修改冲突时草稿保留,需重新加载后再编辑。
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预览并迁移模型引用
工作区管理员可在模型页预览预设、启用 Key 白名单、共享集合和本人私有集合的精确模型引用,勾选确认后每批最多替换 100 项。预览十分钟有效,绑定当前个人会话和工作区。版本或模型目录变化须重新预览;响应丢失可查询回执或重试原操作,不重复修改。
预设追加可恢复的新版本,集合保留备注;已有目标条目的集合需手工处理。通配符、别名、他人私有数据、聊天记录和外部应用不自动改写。核对替代模型价格、能力与隐私策略,再验证实际调用。集合中的退役模型保留记录并停用试用入口;事件前有效预设和 Key 的精确引用也纳入模型退役/价格通知。
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使用虚拟 API 密钥
通过 Bearer Token 发送 AIDMX 密钥。虚拟密钥用于隔离应用,可设置预付预算、速率限制、模型和供应商允许列表。
Authorization: Bearer mmk-••••••••推理 API 密钥使用 mmk- 前缀。已发放的密钥继续遵循原有的停用、过期和轮换规则。
客户身份验证绑定组织,成员及其工作区共用认证主体。七个区域默认要求通过认证后才能发起充值和使用组织推理 Key;认证未完成或被撤销时返回 403。登录成功和邮箱验证不等于身份验证通过。请由组织所有者或管理员在“组织管理 → 实名认证”完成流程。
模型调用使用 mmk- 推理 Key;账户、充值、会话及组织治理使用个人登录会话。托管控制台由安全 Cookie 保持会话,不需要把登录凭据复制到 SDK。urm- 管理 Key 仅可执行已授权的工作区管理操作,不能调用模型或操作钱包。工作区管理路径使用 /api/v1/workspaces/{workspace_id}/...;推理 Key 已绑定工作区,不能用 X-ModelMix-Workspace 切换到其他工作区。
参数与模型能力
按所选接口的字段填写参数。先在模型详情查看输入类型、工具调用、结构化输出、上下文及输出上限;同一模型的不同端点可能支持不同参数,不能只看模型名称判断。
思考开关与强度
网页聊天和创意工作台只提供所选模型支持的思考选项。可关闭思考的模型才允许关闭,必须思考的模型不能强制关闭;强度档位也因模型而异。API 可按端点能力使用 reasoning.enabled / reasoning.effort 或相应原生字段,不要把 reasoning 与 enable_thinking、thinking、reasoning_effort 混用,或同时传入互相矛盾的开关。
{
"model": "MODEL_ID_SUPPORTING_THINKING_OFF",
"messages": [{"role": "user", "content": "Hello"}],
"reasoning": {"enabled": false},
"max_tokens": 256
}输出上限
Chat Completions 使用 max_tokens 或模型支持的 max_completion_tokens,Responses 使用 max_output_tokens,Google 使用 generationConfig.maxOutputTokens。每次只设置所用协议对应的一项。未填写时使用模型默认输出配置;需要更长回复时可显式申请,但不能超过端点公布的输出及上下文上限。工具定义、历史消息和图片也占用输入空间。
部分百炼 Responses 模型在开启思考时,不能通过 max_completion_tokens 限制思考与回答的总量;可按错误提示使用 max_tokens 限制回答,或改选支持该能力的模型。参数被拒绝时先核对错误信息和模型能力,不要反复重发同一请求。
按需求选择路由
通过 provider 对象在发送请求前筛选和排列可用端点。显式限制始终优先于系统学习的性能数据。
{
"model": "YOUR_CHAT_MODEL_ID",
"provider": {
"order": ["YOUR_PRIMARY_PROVIDER", "YOUR_BACKUP_PROVIDER"],
"sort": "latency",
"zdr": true,
"allow_fallbacks": true
}
}将 YOUR_CHAT_MODEL_ID 和供应商占位符替换为当前目录中的模型与端点供应商 ID。GET /v1/models/{model_id}/endpoints 可查询端点;order 指定优先顺序,only 才限制候选供应商。zdr: true 会过滤所有不满足零留存要求的端点,可能使请求无可用路由。
不指定 provider.sort 时使用工作区路由默认值;默认 balanced 综合价格、延迟、端点权重与优先级。显式 sort 支持 price、latency、throughput 和 exacto;balanced 是默认策略名称,不是请求中可传的 sort 值。exacto 排序不代表通用模型质量榜单,请结合实际使用效果选择。
按任务和费用档位选择模型
使用 modelmix/auto 进行任务分类、模型选择和跨模型回退。通过 cost_tier选择费用档位:low、medium、high、xhigh 或 max,默认为 medium。供应商排序在模型选择之后执行。
{
"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"]
}]
}自动选择会参考任务类型、成本档位和本站近七天的已完成消费情况;缺少数据时使用目录默认策略。它不代表通用模型质量排名,仍会遵守工作区及密钥的模型、供应商和隐私限制。
当上次使用的模型仍位于前三个符合条件的候选模型中时,会话优先继续使用它。连续五分钟没有成功请求后,会话偏好到期。显式限制始终有效;音频和视频生成仍需明确指定模型。
通过响应头 x-request-id 在请求记录中查看路由、供应商尝试、交付和结算状态。控制台路由设置仍按工作区权限管理。
为故障做好准备
使用 models 指定按优先级排列的回退模型。AIDMX 会先尝试主模型的所有健康端点,再切换到下一个模型。
{
"model": "YOUR_PRIMARY_CHAT_MODEL_ID",
"models": [
"YOUR_BACKUP_CHAT_MODEL_ID"
]
}主模型与回退模型都需要在当前区域和 Key 权限范围内启用,并符合本次请求的能力、价格及隐私限制。请替换示例占位符;回退列表不会绕过这些限制。
流式输出与中断
设置 stream=true 使用所选协议的流式输出。保存响应头 x-request-id,可在请求记录中查询状态。中途断开仍可能产生费用;先核对原请求,再决定是否重新生成,避免重复提交。
查看接口与请求排查 →录音、转写与语音下载
打开聊天,在输入框上方选择“音频”,将音频模式切换为“转写”并选择可用模型。可录音和本地试听,最多两分钟;也可上传最多 7 MiB 的 WAV、MP3 或 FLAC。录音需要 HTTPS 和浏览器麦克风权限,确认转写前音频仅留在当前标签页,不产生模型费用。切到后台或离页会中断并丢弃录音。
网页聊天使用当前登录账户,无需手工连接推理 Key;确认工作区及价格后明确提交付费转写,可编辑结果再插入聊天草稿。提交结果未知时应查询原任务并核对请求记录;不要重复提交。选择“音频 → 配音”可将文字生成语音,通过网关鉴权试听、下载或保存到 Files,重试下载不会重新生成。
支持实时转写的模型可在音频模型试用界面使用:开始后音频即时发送至所选供应商,最长 120 秒,按实际用量计费。这是语音转文字功能,不是双向实时语音通话。
各类模型的通用配置
以下步骤适用于把文本、图片、音频、视频、向量和重排模型接入自己的应用。使用 ModelMix 网页聊天或创意工作台时,登录后选择工作区和模型即可,页面会使用当前账户。第三方应用和下方调用示例使用工作区推理密钥。
- 登录控制台,确认当前组织和工作区,完成页面要求的身份认证,并确认有可用余额或适用的套餐点数。
- 打开模型目录,按任务类型选择模型,查看输入/输出类型、支持参数、限制和价格。复制完整的模型 ID,不要填写展示名称或供应商的上游型号。
- 在同一工作区创建推理密钥,核对允许使用的模型、消费上限和有效期。应用中的 API Key 填写这把 mmk- 开头的密钥。
- 在支持 OpenAI 兼容接口的客户端中填写下方 Base URL、推理密钥和模型 ID。如果工具要求完整请求地址,再追加一次对应接口路径。确认工具支持目标任务,例如只有文本对话的客户端可能没有生图或视频生成功能。
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
Base URL | 必填 | https://stg-api.aidmx.net/v1 |
API Key | 必填 | 当前工作区的 mmk- 推理密钥,保存在应用的受保护配置中。 |
model | 必填 | 从模型目录复制的完整 ID,各种任务应选择对应类型的模型。 |
Base URL 以 /v1 结尾,模型目录也使用同一地址下的 GET /v1/models。不要在 Base URL 输入框中追加 /chat/completions。网站登录密码和管理密钥不能代替推理密钥。
准备 Python 示例环境
使用 Python 3 并安装 requests。在同一个终端设置接口地址和实际推理密钥。下方每个示例均为独立完整文件,运行前替换全大写的模型或音色占位值。若系统使用 python3 命令,请将命令中的 python 换成 python3。
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 配置
python -m pip install requests
$env:MODELMIX_BASE_URL = "https://stg-api.aidmx.net/v1"
$env:MODELMIX_API_KEY = "mmk-REPLACE_WITH_YOUR_KEY"查询当前密钥可用的模型 ID
模型列表默认筛选文本输出。查询所有类型时,加上 output_modalities=all,避免漏掉图片、音频、视频和向量模型;available_only=true 用于筛选有可调用配置的模型。需要缩小范围时,可再传 task_type,取值为 chat、image、speech、transcription、video、embedding 或 rerank。目录可用不保证供应商此刻一定可用。
列出模型
保存为 list_models.py,替换模型 ID 和示例中的占位值,运行 python list_models.py。
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"])
先用一条短消息、一张图片或一段短音视频验证。实际调用会按用量计费,示例不会自动重发生成请求。遇到超时或结果不确定时,先根据请求号或已保存的任务查询记录,再决定是否重新提交。不要把密钥放进公开前端代码或对外分享的示例。
扣子视频工作流
使用控制台持久视频任务时,可在扣子导入下方 OpenAPI,配置 Authorization 请求头中的 Bearer 推理密钥;密钥保存在插件的鉴权设置中。保存返回的任务 ID,按 Retry-After 或 poll_after_seconds 查询原任务。requires_action=true 时等待管理员核查,不能重新提交已经付费的任务。
https://stg-api.aidmx.net/api/v1/videos/openapi.json费用仍为 pending 时也可下载成功结果。结果或费用未知时保留原任务;expires_at=null 表示未设置自动到期,不代表结果永久有效。下载和保存仍受任务权限及产物保留期约束。
文本模型:对话与文本生成
文本模型用于对话、写作、翻译和代码等任务。首次接入可使用 Chat Completions;使用其他协议时,确认客户端和所选模型均支持。
配置步骤
- 在模型目录选择 task_type=chat 的模型,复制 ID,查看上下文、输出上限和支持的协议。
- 在客户端填写 Base URL、推理密钥和模型 ID,或使用下方示例调用 POST /v1/chat/completions。
- 先保留模型默认参数,发送一条短消息。成功后再逐项添加历史消息、输出上限、思考设置或流式输出。
参数说明
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
model | 必填 | 完整的聊天模型 ID。 |
messages | 必填 | 按顺序排列的 role/content 消息数组。首次只传 user 消息,多轮对话需包含此前的 user 和 assistant 消息。 |
max_tokens / max_completion_tokens | 可选 | 使用端点支持的一项,限制输出 Token,并遵守上下文及输出上限。省略时使用模型默认配置,部分思考模型的总量包含思考 Token。 |
temperature / top_p | 可选 | 仅在模型支持时设置采样参数。temperature 为 0–2,top_p 为 0–1;建议先用默认值,再单独调整一项。 |
stream | 可选 | true 返回 SSE 事件,客户端需要持续读取增量直到完成;false 或省略时返回完整 JSON。 |
reasoning | 可选 | 按模型详情支持的范围设置 enabled、effort,不与 enable_thinking、thinking、reasoning_effort 混用。 |
response_format / tools | 可选 | 结构化输出、客户端函数工具需要模型支持;返回函数调用后,由你的应用执行函数并回传结果。 |
完整示例:文本对话
保存为 text_chat.py,替换模型 ID 和示例中的占位值,运行 python text_chat.py。
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"))
可选完整示例:流式对话
保存为 text_stream.py,替换模型 ID 和示例中的占位值,运行 python text_stream.py。
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.")
可选完整示例:Responses
保存为 text_responses.py,替换模型 ID 和示例中的占位值,运行 python text_responses.py。
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"))
验证方法
- 预期 HTTP 200,回答包含 ModelMix connected。Chat Completions 从 choices[0].message.content 读取文本;Responses 从 output 中类型为 output_text 的消息内容读取。
- 流式调用应能逐段显示文本,并最终收到 [DONE]。流中断时也可能已经产生用量。
- 参数返回 400 时,对照所选模型的支持范围检查。Responses 示例使用 input 和 store:false;其输出上限字段为 max_output_tokens,与 Chat 字段不同。
示例会输出 HTTP 状态和 x-request-id。请在控制台“请求记录”搜索该请求号,核对模型、状态、用量和费用;生成完成时费用可能仍待结算。 错误码与请求排查 →
图片模型:生成、理解与编辑
生成图片使用 image 类型模型;理解图片使用支持图片输入的 chat 模型。编辑图片还需要模型具备图片编辑能力,能看图的聊天模型不代表能生图或改图。
配置步骤
- 按目标选择生图模型、支持图片输入的聊天模型,或支持编辑的图片模型,并在详情中确认输入格式、输出尺寸和价格。
- 网页聊天中选择“图片”、模型并填写描述。应用生图使用 /v1/images/generations,看图使用 /v1/chat/completions,改图使用 /v1/images/edits。
- 首次只生成一张并使用默认尺寸。上传示例需要把一张真实的小尺寸 PNG 命名为 reference.png,放在脚本同目录;更换格式时同步修改 MIME 类型。
参数说明
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
model | 必填 | 按生图、看图或改图选择对应能力的完整模型 ID。 |
prompt | 生图、改图必填 | 描述主体、场景和风格;编辑时写清要改动及保留的内容。 |
n | 可选 | 生成张数,建议先填 1;最大张数及每张价格以模型为准。 |
size / quality | 可选 | 从模型支持的尺寸、质量档位中选择;1024x1024 等值只适用于支持它的模型。首次调用可省略。 |
response_format | 可选 | 模型支持时,url 返回图片地址,b64_json 返回 Base64 内容。示例兼容两种返回方式,无需强制指定。 |
messages[].content | 看图必填 | 由 text 和 image_url 内容项组成;image_url.url 填模型支持的 HTTPS 图片地址,或含 MIME 类型及 Base64 内容的 data URL。 |
image | 改图必填 | 使用 multipart 上传图片文件。不要手工填写 multipart 的 Content-Type,requests 会自动生成 boundary。 |
seed / watermark | 可选 | 仅在模型声明支持时设置随机种子、水印;固定 seed 不保证不同模型或版本产生相同图片。 |
完整示例:生成并保存图片
保存为 image_generate.py,替换模型 ID 和示例中的占位值,运行 python image_generate.py。
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)
完整示例:理解本地图片
保存为 image_understand.py,替换模型 ID 和示例中的占位值,运行 python image_understand.py。
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"])
完整示例:上传图片并编辑
保存为 image_edit.py,替换模型 ID 和示例中的占位值,运行 python image_edit.py。
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)
验证方法
- 生图应返回包含图片的 data,并保存 modelmix-image 文件。打开图片检查红色帆船和场景。ModelMix 图片下载地址可能需要原密钥鉴权,外部图片地址不能附带 ModelMix 密钥。
- 看图时使用主体、颜色清晰的简单图片,对照回答检查;改图时对比原图与结果,确认修改确实发生。
- 上传失败时检查实际格式、MIME 类型、文件大小和模型能力。生成成功后下载失败,应先恢复原结果,避免立即重新生图。
示例会输出 HTTP 状态和 x-request-id。请在控制台“请求记录”搜索该请求号,核对模型、状态、用量和费用;生成完成时费用可能仍待结算。 错误码与请求排查 →
音频模型:语音合成与转写
语音合成把文字变为声音,使用 task_type=speech;语音转写把声音变为文字,使用 task_type=transcription。请按转换方向选择模型。
配置步骤
- 在目录中选择语音合成或转写模型,查看音色、语言、音频格式、输入限制和计费单位。
- 网页聊天中选择“音频 → 配音”或“音频 → 转写”,再选择模型。应用合成使用 POST /v1/audio/speech,转写使用 POST /v1/audio/transcriptions。
- 合成示例中把音色占位值替换为该模型有效的音色 ID,并确认支持 WAV 输出。转写示例需在脚本同目录准备一段名为 sample.wav 的短音频。
参数说明
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
model | 必填 | 合成填写 speech 模型 ID,转写填写 transcription 模型 ID。 |
input | 合成必填 | 需要朗读的文字,先用一句短文本测试。网页配音最多 3,000 字符,模型可能有更低限制。 |
voice | 合成必填 | 该模型支持的准确音色 ID,不是显示名称。不同模型的音色及权限不同,不要直接照搬其他供应商的音色。 |
response_format | 可选 | 合成返回音频字节,可选格式如 wav、mp3,以模型支持为准;转写常用 json、text,verbose_json 和时间戳需要模型明确支持。保存文件后缀需与格式一致。 |
speed / instructions | 可选 | 合成语速、风格指令的支持范围因模型而异,基础调用成功后再添加。 |
file | 转写必填 | multipart 表单中的实际音频文件,不是本地路径字符串。网页上传支持 WAV/MP3/FLAC,最大 7 MiB;网页录音最长两分钟。 |
language | 可选 | 在模型支持时填写输入语言代码,如 zh、en;否则省略,让模型自动识别。 |
完整示例:文字生成 WAV 语音
保存为 audio_speech.py,替换模型 ID 和示例中的占位值,运行 python audio_speech.py。
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"))
完整示例:上传 WAV 并转为文字
保存为 audio_transcribe.py,替换模型 ID 和示例中的占位值,运行 python audio_transcribe.py。
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"])
验证方法
- 合成成功后应保存 modelmix-speech.wav,在本地播放,检查朗读内容与 input 一致,文件格式与后缀一致。
- 转写时用一段清晰短句测试,检查 JSON 中的 text 是否包含对应文字。静音、噪声及不支持的语言会影响结果。
- 音色或格式报错时,改用当前模型支持的值。录音和实时转写的操作见“录音与语音转写”;实时转写属于语音转文字。
示例会输出 HTTP 状态和 x-request-id。请在控制台“请求记录”搜索该请求号,核对模型、状态、用量和费用;生成完成时费用可能仍待结算。 错误码与请求排查 →
视频模型:创建、查询与下载
视频生成为异步任务:创建一次,保存任务 ID,查询状态,完成后下载。文生视频和参考图生视频的支持范围因模型而异。
配置步骤
- 选择 task_type=video 的模型,核对时长、分辨率、比例、参考素材和价格。示例采用 4 秒、1280x720,请选择支持这些值的模型,或按详情一起修改。
- 网页聊天中选择“视频”、模型,填写描述、时长和比例;模型提供参考图入口时再添加。应用通过 POST /v1/videos 创建任务。
- 保存返回的 id,使用原密钥通过 GET /v1/videos/{id} 查询状态,完成后通过 GET /v1/videos/{id}/content 下载。查询和下载不会重新生成。
参数说明
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
model / prompt | 必填 | 视频模型 ID,以及场景、动作和风格的文字描述。 |
seconds | 建议明确填写 | 模型支持的输出秒数,标准请求使用字符串,例如 "4";可用时长因模型而异。 |
size | 建议明确填写 | 模型支持的宽×高字符串,例如 1280x720,不要直接填 16:9;需同时满足模型的分辨率及时长限制。 |
input_reference | 可选 | 支持图生视频时上传参考图,示例使用 multipart。上传前核对模型要求的尺寸、格式和参考图用途。 |
generate_audio / seed / watermark | 可选 | 仅填写所选模型明确支持的参数;视频模型不一定支持生成声音。 |
id / status | 响应字段 | id 用于后续查询原任务,status 达到 completed 后下载;failed、cancelled 等状态需查看错误。 |
Retry-After | 响应头 | 响应提供时按建议间隔查询;示例缺省每五秒查询,并在达到次数上限后停止等待。 |
完整示例:生成视频、恢复查询并下载
保存为 video_generate.py,替换模型 ID 和示例中的占位值,运行 python video_generate.py。
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.")
可选完整示例:参考图生视频
保存为 video_reference.py,替换模型 ID 和示例中的占位值,运行 python video_reference.py。
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.")
验证方法
- 首次提交成功后,确认 modelmix-video-task.json 已保存返回的 ID。再次运行任一视频示例会读取该文件,继续原任务;需使用创建任务时的密钥和地址。
- 状态变为 completed 后,应得到可播放的 modelmix-video.mp4,检查场景和时长。等待中或本地超时不代表生成失败,可再次查询已保存的任务。
- 确认原任务结果和费用后,如需明确生成新视频,再移走或删除任务文件。若创建请求超时且未保存 ID,先查请求记录;立即再次运行可能提交第二个付费任务。
示例会输出 HTTP 状态和 x-request-id。请在控制台“请求记录”搜索该请求号,核对模型、状态、用量和费用;生成完成时费用可能仍待结算。 错误码与请求排查 →
向量模型:把文本转换为向量
向量模型把文本转换为数值向量,用于检索和相似度计算。每条输入返回一个向量,不直接返回聊天回答或文档排名。
配置步骤
- 选择 task_type=embedding。通过接口查询时加上 output_modalities=all,并核对维度、编码、批量条数及上下文限制。
- 配置 Base URL 和推理密钥,调用 POST /v1/embeddings。首次传两条短文本,使用默认维度和 float 编码。
- 文档入库和后续查询需使用相同的模型、维度及文本预处理方式;更换向量模型或维度后,通常需要重新生成已有文档向量。
参数说明
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
model | 必填 | 完整的 embedding 模型 ID。 |
input | 必填 | 非空字符串或字符串数组,批量上限以模型为准;长文档需由应用先分段。 |
dimensions | 可选 | 模型支持的输出维度整数;省略时用默认值,不要假定所有模型都能任意调整维度。 |
encoding_format | 可选 | float 返回数值数组,便于验证;支持 base64 的模型可返回编码内容,计算前需要按对应向量格式解码。 |
input_type / text_type / instruct | 可选 | 部分模型区分 query、document 输入或支持检索指令,仅按该模型支持的参数名和取值使用,不是所有向量模型的通用必填项。 |
data[].index / embedding | 响应字段 | index 对应原输入的下标,embedding 为向量;批量存储时应保留该对应关系。 |
完整示例:生成并检查向量
保存为 embeddings.py,替换模型 ID 和示例中的占位值,运行 python embeddings.py。
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"))
验证方法
- 两条输入应返回两个向量,index 为 0、1。示例会检查维度一致,且所有元素均为有限数值。
- 核对实际维度与模型详情或显式设置的 dimensions 一致,向量数据库字段也需要使用相同维度。
- 验证检索效果时,使用相同配置生成查询及相关、无关文本的向量,再比较相似度;接口成功本身不等于检索质量符合预期。
示例会输出 HTTP 状态和 x-request-id。请在控制台“请求记录”搜索该请求号,核对模型、状态、用量和费用;生成完成时费用可能仍待结算。 错误码与请求排查 →
重排模型:按相关性排序候选文档
重排模型根据查询对候选文档评分。应用先检索出候选文档,再交给模型排序;重排本身不会替你检索文档或生成聊天回答。
配置步骤
- 选择 task_type=rerank,确认查询长度、候选文档条数和长度、支持参数及价格。
- 调用 POST /v1/rerank,传入明确的 query 和少量候选文档字符串。保留原数组顺序,以便按返回下标找回原文档。
- 用 top_n 指定需要的结果数量,不超过候选条数。首次可像示例一样,传三条候选、取前两条。
参数说明
| 参数 | 是否必填 | 填写方法 |
|---|---|---|
model | 必填 | 完整的 rerank 模型 ID。 |
query | 必填 | 非空的检索问题或相关性目标,例如如何创建 ModelMix API Key。 |
documents | 必填 | 候选文档字符串数组,首次使用纯文本,并遵守模型的条数和上下文限制。 |
top_n | 可选 | 需要保留的最高相关结果条数,为正整数且不超过 documents.length。 |
return_documents | 可选 | 支持时设为 true 可返回文档文本;设为 false 时,使用返回的 index 从原 documents 数组取回内容。 |
results[].index | 响应字段 | 原始 documents 的下标,从 0 开始,不是重排后的名次。 |
results[].relevance_score | 响应字段 | 分数越高表示本次结果中越相关,不应直接比较不同模型的分数标尺。 |
完整示例:重排并找回原文档
保存为 rerank.py,替换模型 ID 和示例中的占位值,运行 python rerank.py。
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"]])
验证方法
- 示例应返回两条结果,下标有效且不重复,分数按降序排列,并在分数旁打印对应原文档。
- 检查“创建密钥”的操作说明是否排在无关帆船文本之前;不符合预期时检查查询表达、候选内容及模型对语言、任务的适用性。
- 长度或批量报错时,缩短单条候选或减少条数。比较查询效果时,保持候选集合和模型配置一致。
示例会输出 HTTP 状态和 x-request-id。请在控制台“请求记录”搜索该请求号,核对模型、状态、用量和费用;生成完成时费用可能仍待结算。 错误码与请求排查 →
标准批处理
先通过 /v1/files 上传 purpose=batch 的 JSONL,再通过 /v1/batches 提交 input_file_id、endpoint 和 completion_window。每个文件使用一个已发布模型及一个 endpoint,最多 100 条唯一请求。保存任务 ID,通过原 Key 查询任务及读取结果文件。按实际用量结算;提交后无需保持页面打开,也不要因暂未完成而重复提交。
查看接口与请求排查 →保存会话,比较模型,继续对话
聊天输入框上方可切换“对话、图片、视频、音频”;仅显示当前工作区存在可用模型的类型。选择类型后,在模型选择器中选模型,再填写描述和参数。音频支持录音或上传 WAV/MP3/FLAC 转写、编辑后插入草稿,以及将文字生成语音;录音最多两分钟、上传最大 7 MiB,语音合成最多 3,000 字,图片或视频描述最多 4,000 字。每次生成单独计费;录音、试听、插入草稿、下载和保存不会再次生成。
登录控制台后打开聊天,新建或恢复私人会话。网页聊天使用当前登录账户,无需手工连接推理 Key;切换工作区后会按该工作区的权限和策略调用。对话模式可选择最多三个模型并行回答,选中的回答会进入下一轮上下文。每个模型单独计费,实际费用以请求记录为准。第三方应用和 SDK 仍需使用工作区推理 Key。
视频模式可按模型能力添加首帧参考图、设置时长和比例。媒体任务可在聊天中的结果卡片查看进度,或从“媒体生成记录”找回;记录中可按类型筛选、下载或保存到文件,并复用描述及支持的参考图。重新查询记录不会重复生成。提交结果不确定时,先查询原任务和请求记录。
聊天生成在后台执行,支持流式预览、关闭页面后恢复结果和显式取消。重新打开会话或恢复订阅只读取原任务,不重发付费请求。取消或中断仍可能产生已经发生的费用;任务状态不确定时先核查请求记录。生成任务恢复记录保留 24 小时,已保存到会话的回答按会话保留。
会话内容加密保存,按用户和工作区隔离,直到你删除。每个会话最多 40 轮、512 KiB;支持已有文档和图片附件、系统指令、参数和工具。刷新或重试保存不会自动重发推理。
会话分支图可切换原会话、兄弟分支和后续分支。分享会话时,先预览并确认标题、消息和已选回答,再创建 1、7 或 30 天有效的只读链接。系统提示、未选答案和附件文件不会随链接公开,但消息文字本身仍可能包含隐私信息。后续编辑不更新已分享快照;替换或撤回链接会使旧链接失效,删除原会话也会撤回分享。阅读者已经保存的副本无法收回。
/api/v1/chat/sessions 使用账户会话鉴权;保存需提供 expected_revision 与唯一 operation_id。该应用接口独立于模型推理 API。
AI 助手与工作区协作
桌面端与云客户端
登录控制台并选择工作区,打开“客户端 → 登录桌面端”或“登录云客户端”。登录链接只能使用一次,两分钟后过期;桌面端未打开时会跳转到下载页。已安装客户端也可直接使用 ModelMix 账号登录,请选择与当前环境对应的安装包。
云端运行实例与共享成果
在“工作台 → 智能体与协作”中,由工作区管理员先在“服务设置”启用服务并配置组织推理授权。点击“新建运行实例”,选择项目、有权使用的输入文件或模板,设置执行资源、消费上限和最长运行时间。创建后在列表中点击“打开智能体”,再在对话中输入具体任务要求。排队表示正在等待执行名额,请先核对已有实例再新建。
云端运行实例是智能体的执行环境,一个实例内可以有多条对话。客户端会话列表展示具体对话,控制台列表展示云端运行实例及其用量;客户端本地会话不在控制台列出。若要保存说明后自动执行,请创建“组织自动化”,每次定时、手动或事件触发都会把任务说明发送给智能体执行。
实例对话历史为私人内容;需要协作时,明确发布选定成果或模板为工作区共享副本,并通过版本记录管理。停止运行仍可能结算已经发生的模型费用。删除运行实例会清理其私人历史和云端任务文件,项目文件及已发布的工作区共享副本继续保留。云端资源订阅不包含模型推理费用。
打开智能体与协作 →使用创意工作台
在控制台选择“工作台 → 创意工作台”,在新标签页打开;使用 ModelMix 账号登录并确认工作区。模型、权限和计费自动接入 ModelMix。项目、画布、Agent 历史和素材按用户及工作区隔离,同一工作区成员不会自动共享私人画布。
- 新建或打开项目,添加文本、图片、视频或音频节点,选择对应任务的可用模型,核对价格和生成参数后提交。
- 参考图片、视频、音频,以及时长、分辨率和比例取决于所选模型,请按页面提供的选项及素材处理提示操作。选择“跟随参考图”时,无需另填比例。
- 等待生成与保存完成。生成成功但画布尚未保存时,复查原任务并完成保存,不要重复提交付费生成。重新打开项目可恢复已保存内容;重新生成则属于新的计费操作。
创意工作台与 Agent 云端共享组织资源池及一次 7 天试用。项目文件和创意素材按实际大小占用套餐内的共享存储,模型生成另行计费。发起付费生成前,请确认订阅状态及可用余额。
打开创意工作台 →运营工作台与渠道身份
运营工作台是面向已分配渠道身份的独立门户。先正常注册 ModelMix 账号,再由有权限的管理员分配渠道身份,使用该账号登录运营方提供的工作台地址。普通用户注册或成为组织所有者不会自动获得渠道权限。
- 平台管理员在 MB 后台新增运营中心。中心管理员先在“角色管理”创建自定义角色,再于新增或修改员工时分配一个或多个角色;可分别配置本中心的业绩、客户、报价、团队和员工管理权限,也可继续使用内置只读角色。
- 会员通过代理列表新增或修改直属代理;代理登录后展示用户列表。运营中心、会员和代理均可查看自己整个下级范围内的客户,包括下级推荐带来的客户。邀请链接携带 8 位大写字母与数字组成的邀请码,排除 0、1、I、L、O 等易混字符。
- 员工只能授予自己拥有的权限,工作台角色不会授予 MB 或 OPS 后台权限。角色调整在下一次请求时生效。折扣变更需在页面允许的范围内预览并确认;最后一名中心管理员停用或降级前须先完成交接。
无法进入时,请联系渠道管理员核对身份分配和工作人员权限。渠道管理员不代设或替换用户的账号密码。
让隐私策略落到请求中
默认不存储提示词和响应。可按请求要求零数据保留端点,或禁止使用采集数据的供应商。
账户区域与数据处理地域
中国区 / 美国区用于确定账户、钱包币种、模型目录和服务政策,不保证数据只在中国或美国处理。模型、文件、搜索等服务的数据处理地点可能不同;有地域要求时,请在使用前向平台支持确认。
关闭提示词日志或选择零留存端点不等于地域保证,也不会删除显式保存的聊天、文件或账务记录。供应商留存、本站正文日志和业务数据保留是独立设置。
组织与成员请求防护策略
Guardrail 可由工作区管理员管理当前工作区,也可由组织 owner/admin 在所有下属工作区统一管理。组织规则与工作区规则取严格交集,工作区管理员不能放宽继承策略;阻断优先于遮蔽。
all_keys 覆盖范围内所有服务 Key 和个人 Key;member_ids 仅覆盖所选成员当前及未来的个人 Key,不包含其创建的服务 Key。工作区可组合 key_ids 和 member_ids,组织范围仅支持 all_keys 或 member_ids。
个人会话需具备对应范围的管理员权限。工作区护栏也接受明确授权的 urm- 管理 Key:guardrails:read 用于读取、试运行和分配预览,guardrails:write 用于创建、修改和归档。管理 Key 不能操作组织护栏;普通推理 Key 和系统管理令牌不能管理护栏。每范围最多 100 条有效策略,最多选择 500 个 Key 和 500 名成员。修改及归档必须提供 expected_revision;冲突返回 409 并保留原策略。
预览仅表示当前清单,最多返回 100 个示例 Key,完整数量不截断;它不校验推理权限、余额、到期时间或上游可用性。样例试运行不写事件或调用供应商,执行事件仅记录规则元数据,不保存命中的提示内容。
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=2spending 支持每日、每周、每月及累计共享预算,使用组织计费币种和 UTC 周期,统计在途、待结算费用及实际钱包扣款(含 BYOK 服务费)。reserved 字段包含尚未结算的额度占用,不代表新推理请求冻结钱包。修改成员或 Key 分配不会清零既有归属用量。GET /api/v1/workspaces/{workspace_id}/guardrails/budgets 可查看当前范围的上限、已用、预留和剩余额度;组织范围使用相同后缀。收紧上限低于已用加预留时返回 409,推理超额时在调用供应商前返回 402。
prompt_injection.allowlist 最多包含 20 条 name/text 例外,仅对本策略内一个完整文本字段进行区分大小写的精确匹配。前后空白也必须一致;不豁免其他策略或敏感信息检查。命中记录只保留例外名称。内容试运行不评估支出或锁定资金,spending_evaluated 始终为 false。
套餐、每日点数与存储
在“产品订阅”中选择 ModelMix,查看当前组织可购买的套餐、报价和权益;列表为空表示当前没有可购买套餐。组织所有者或具备财务管理权限的用户可预览订单,按页面提供的组织余额或支付渠道付款。付款后刷新订单及订阅,确认周期已生效;待付款、已付款待开通都不等于权益已可用。
打开产品订阅 →已生效的 ModelMix 套餐包含每日点数和组织共享存储。每日点数按上海时间(Asia/Shanghai)零点重置,不累计到下一天;每点抵扣金额以购买时权益和币种为准。点数用于抵扣符合条件的模型用量,不是可提现或退款的钱包本金;已用、预占及剩余点数可在套餐权益中查看,最终消耗随实际用量结算。未订阅的按量账户继续按钱包规则使用。
“点数不足或套餐到期时,允许使用组织钱包余额”是单独的开关,默认关闭。关闭时,即使钱包有余额,点数不足或已启用过的套餐到期也可能返回 402;先查看套餐状态和剩余点数,再选择续费或明确开启钱包回退。开启后仍受钱包余额、Key、工作区及护栏预算限制;充值不会自动续订套餐。
存储总容量和单文件上限以当前权益及文件页面为准;套餐存储由同组织工作区共享,可用的存储扩容包另行增加容量。到期或暂停可能使存储变为只读:不能继续上传,仍可下载允许下载的文件并清理空间。续费、扩容及恢复写入以页面的生效状态为准,不能仅凭支付返回页判断。
Agent 云端与创意工作台资源
在“产品订阅”选择 Agent,查看云端计算资源套餐。Agent 云端与创意工作台共享一次 7 天试用,从首次开通云端时开始;查看套餐不会启动试用,切换入口不会重新获得试用。到期后需订阅才能继续云端执行。
有效订阅提供席位、CPU、内存、云盘及内含出站流量。团队资源是组织共享总额度,由 Agent 与创意工作台共同使用,不是每名成员各有一整份。订阅期内不限制累计运行小时数,仍受同时可用资源及单任务最长运行时间约束;购买前请核对当前套餐规格与价格。
交互环境空闲 15 分钟后休眠,活跃任务继续运行。确认停机后释放 CPU 和内存,已保存文件继续占用组织存储。到期停止执行,实例数据库按 7 天保留政策回收;文件存储按剩余有效权益核定,超额时转为只读,续费或清理至额度内即可继续写入。
模型生成另行计费。项目文件和创意素材共用套餐内的组织存储,存储扩容增加同一份额度。出站流量先用套餐内含额度,超出后按 1 元/GB 从组织余额扣除;月度额度不结转,共享试用包含 5 GB。购买云端资源套餐不会自动增加 ModelMix 每日点数。
查看云端套餐 →用量、可用额度与结算
同一组织的成员和工作区共享组织钱包。钱包余额与可用额度可能不同:进行中的请求、待结算费用、退款冻结等都会占用可用额度。Key、工作区及防护策略也可能设置独立预算;充值不会自动提高这些预算。套餐点数与钱包回退另见套餐说明。
余额或预算仅剩少量时,可能仍允许最后一笔请求;最终费用按实际用量计算,可能使余额为负或超过预算。余额或预算耗尽后会停止新的付费调用。遇到 402 请检查余额、预算及套餐状态;遇到 429 请减少并发并按提示等待。
生成完成不等于费用已结算。billing_status=pending 或 cost_is_provisional=true 表示费用仍待结算,settled 才是最终费用。保留响应头 x-request-id 或返回的 generation_id,在“请求记录”查看状态和明细;重新查询不会再次推理。钱包流水和用量汇总可能稍后更新。
GET /api/v1/billing
Authorization: Bearer mmk-...
GET /api/v1/activity/{generation_id}
Authorization: Bearer mmk-...请求结果或费用等待核验时,请保留原请求并联系支持,不要因为暂未显示最终费用而重新提交。取消或中断生成仍可能结算已经产生的用量。
充值、费用与退款
在“订阅与余额 → 充值订单”预览订单、核对到账额度和应付总额,再按页面提供的方式付款。币种跟随组织钱包,与网页语言无关。当前充值平台手续费为 0%,已有订单保留原报价,实际以本次订单显示为准。创建待付款订单或从收银台返回都不代表已经到账,请在原订单及资金流水确认。
组织所有者或财务管理员可从已付款充值订单或“退款记录”申请退还未消费本金。金额不能超过页面显示的可退额度,提交后相应资金冻结;进入处理前可按页面状态取消。手续费和赠送额度不属于标准本金退款范围。审核通过不等于已到账,请跟踪最终退款状态。产品订阅退款从“产品订阅”办理,适用该产品自己的退款规则。
自有密钥(BYOK)费用
使用自有供应商密钥时,供应商直接向你的供应商账户收费,ModelMix 可能另收区域政策规定的服务费。月度免额、免额币种和超额费率按七个运营区域分别配置;当前组织当月首次使用时确定该月规则。服务费按组织钱包币种结算。允许回退至平台凭据时,回退请求按平台模型售价计费。
创建或修改 API 密钥时,include_byok_in_limit 默认关闭。开启后,按目录价格折算的 BYOK 用量也计入密钥额度,包括本 UTC 预算周期内已有用量;这不等于把供应商账单再从钱包扣一次。该选项不能保证供应商账户的硬性消费上限,修改前请等待进行中的请求结束。
核对消费和资金记录
先确认当前组织和查询时间。在“请求记录”核对模型、请求号、状态及最终费用;在“消费账单”查看消费明细;在“资金流水”核对充值、扣费及退款。进行中的请求和待结算费用可能尚未出现在最终账单中,不能直接将请求数量当作扣款次数。
组织财务记录需要相应财务权限。导出时保留筛选条件及币种,不要直接相加不同币种的金额。发现差异时,向客服提供相关请求号、订单号或退款编号、发生时间及错误提示,便于核查。
打开资金流水 →按已结算消费申请发票
在目标组织打开“用量与记录 → 发票管理”。组织所有者或财务管理员可维护资料并申请,财务只读用户可查看记录。可开金额汇总同组织、同币种的模型调用、产品订阅及资源等已结算现金消费;充值本身、赠送额度、待结算费用和未核实资金不计入可开金额。
- 核对实名开票主体。抬头、主体类型和企业税号来自实名认证,不能手工改为其他个人或公司;按要求补充企业地址、电话、银行资料和收票邮箱并保存。历史认证缺少可信开票主体时,按页面要求认证或联系支持。
- 查看“可开金额”,选择全部或部分金额申请。提交后占用对应消费额度;财务开始处理前可以撤销,驳回或撤销后释放占用。
- 在本页跟踪申请,显示“已开票”后领取凭证。实际消费退款可能涉及红冲,请在原发票及更正记录中查看进度。
继续使用熟悉的工具
支持自定义 OpenAI 兼容地址的客户端可按集成页配置。示例覆盖 SDK、编程助手、聊天应用及框架,并注明配置位置和官方参考。请选择客户端和模型共同支持的协议、参数及工具能力;配置完成后先发送一条简短消息,并在请求记录中核对结果。
浏览集成指南 →Responses 与文件
Responses 使用 /v1/responses,支持 input、tools、store、background 和流式输出。store 控制是否保留可后续读取的响应;background:true 需要启用存储,不能与 store:false 同时使用。需要续接时保存返回的响应 ID,再通过 previous_response_id 引用,并继续使用创建它的工作区和 Key。
Responses 也支持 /v1/responses WebSocket 多轮调用。store:false 的连接内续接只在当前连接有效,不应当作关闭连接后的持久记录。严格零留存策略可能禁止保存响应、后台任务或文件;需要保存时请先核对工作区隐私设置。
SDK 文件使用 /v1/files,并按任务选择 purpose。控制台文件库及聊天附件使用 /api/v1/files;两类文件 ID 不能假定可以互换。读取、删除或继续使用文件时,保留原有的工作区和凭据,并确认目标模型支持该文件类型。
控制台文件与聊天附件
控制台聊天最多选择 10 个附件,单个附件最多 20 MiB。聊天附件默认为本人私有;账户会话上传时明确选择 visibility=private 或 visibility=workspace。普通上传入口上限为 512 MiB,实际仍受文件设置、存储权益和模型解析能力限制。保存到文件库不代表该文件适用于所有模型。
客户端工具与托管工具
客户端工具使用所选协议的 tools 字段声明。模型返回工具调用后,由你的应用执行工具并按同一协议回传结果;工具调用能力不代表模型会自行访问你的电脑、文件或外部系统。需要结构化参数时,先确认端点支持对应的工具与结构化输出选项。
已开放的 ModelMix 托管工具可由平台执行,例如 modelmix:datetime(当前时间)、modelmix:web_fetch(读取网页)和 modelmix:web_search(网页搜索)。使用前查看“密钥设置 → 工具与插件”,确认工作区允许的工具、调用次数及费用。模型后续回答和工具调用可能分别产生费用。
供应商托管搜索须由所选模型明确支持,并有相应价格。Chat Completions 接入请使用已开放的 ModelMix 搜索工具;供应商原生搜索按支持的 Responses、Messages 或 Google 协议配置。某个模型支持客户端工具,不代表它支持全部托管搜索或其他托管工具。
工作区管理员可在工具页面或 /api/v1/workspaces/{workspace_id}/tool-policy 设置允许使用的托管工具和调用上限;普通推理请求不能绕过这些限制。
API 参考与请求排查
模型推理和模型目录使用 /v1,Google 协议使用 /v1beta;账户、工作区及控制台功能使用 /api/v1。旧 /native/{provider} 和 /api/v1/chat/completions 已停止提供推理服务,已有应用请改用快速开始中的对应地址。
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排查失败时,请记录 x-request-id、模型 ID、时间和错误信息,在“请求记录”搜索请求号查看状态。接口返回 400 时先检查参数与模型能力;401 检查密钥,402 检查可用额度与套餐,403 检查认证及权限,404 检查路径和模型,429 按提示降低并发或等待。不要在工单中附上完整密钥。
组织报告、成员退出与文件夹
组织所有者及管理员可在控制台请求记录、用量分析与导出页切换组织范围,查询所有工作区(包括已归档工作区),按 workspace_id 分组。组织与工作区分页游标不能混用,同名会话也会按工作区和 Key 分开统计。组织报告要求个人会话;管理 Key、服务 Key 和普通成员不具备此权限。
组织导出仍为创建者私有,生成和下载时重新检查组织权限。查询完成后也会复核权限,已撤权的结果不会返回。支持请求记录、聚合分析、会话统计和上游尝试四种 CSV。
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}成员可在“工作区管理”中自行退出:个人和管理 Key 会停用,服务 Key 将要求管理员复核;组织所有者需先转移所有权,最后一名工作区管理员不能退出。Files 提供最多 200 个共享文件夹、8 层嵌套,支持创建、重命名、移动子树和删除空目录。同层级不能重名,不能移动到自身或后代;删除前须移出文件和子目录。移动保留文件 ID;版本冲突要求刷新后重试。上传及推理仍受工作区文件开关和容量限制。
POST /api/v1/audio/tasks/{task_id}/content/save
POST /api/v1/videos/{task_id}/content/save
GET /api/v1/files/{file_id}/content语音和视频任务成功且显示可以保存时,即使 billing_status=pending 也可保存为文件库私密副本;保存不重新生成或重复收取推理费。语音保留 WAV/MP3/FLAC,最大 32 MiB(以页面当前限制为准);视频支持 MP4、最大 64 MiB。原产物过期不影响已保存副本。保存仍受存储容量、单文件上限及权限限制;失败后可重试保存原任务。删除副本释放空间,原产物仍可用时可再次保存。
个人账户通知
在控制台通知中心查看账户安全事件、低余额与工作区预算预警。支持设置预警阈值、筛选未读和分类全部已读。通知保留 90 天,仅个人账户会话可以访问,推理密钥和管理密钥不能访问。
财务预警按已结算钱包费用计算,不含在途及待结算额度。提醒可能延迟,请以当前余额和账单为准。邮件服务启用后,可向已验证邮箱订阅新通知提醒;邮件不包含财务详情。关闭订阅会取消排队邮件,投递失败可在通知列表重试。未收到邮件时,请检查垃圾邮件及站内通知;个人通知目前不提供短信提醒。
推理回执 Webhook 是独立的工作区功能,默认关闭。管理员使用个人会话,通过 GET/PATCH /api/v1/workspaces/{workspace_id}/generation-webhook 配置;同路径追加 /deliveries 查询投递记录。它发送已结算请求的状态、用量及钱包费用元数据;include_media_ready=true 开启已结算媒体的 media.ready 通知,提供需要原 Key 鉴权的任务和下载相对路径,不发送提示词、模型正文、文件内容或供应商签名 URL。接收方应校验 HMAC 签名并按事件 ID 去重,失败重试可能重复或乱序投递。Webhook 可作为查询的补充,不能保证供应商视频链接仍有效,也不替代个人通知订阅。
护栏共享预算支持独立订阅和 1–100% 预警比例,覆盖每日、每周、每月和累计额度。组织策略仅通知组织治理管理员,工作区策略仅通知工作区管理员。个人收藏及本人私有/可访问共享集合也可接收模型退役和价格提醒;集合备注和名称不写入通知。无工作区身份时仍可查看个人收藏提醒和模型目录。
模型提醒匹配早于事件的精确引用、预设/收藏的 latest 别名及 Key 通配规则。别名按发布时目录匹配,规则命中不代表实际使用。退役和价格提醒可分别关闭;关闭余额、工作区预算、护栏预算或某类模型提醒会取消对应排队邮件,失败重试也重新检查订阅和权限。
工作区管理员创建邀请时可选邮件通知,或重新邀请并发送新邮件(旧邀请码随即撤销)。邮件包含 7 天有效的邀请码;受邀人须使用被邀请的邮箱登录,在“工作区管理”中粘贴邀请码接受。
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"]}导出完整查询结果
在请求记录或用量分析页面应用筛选后,选择“导出完整查询”,再到导出中心查看进度、取消任务或下载 CSV。支持请求记录、多维分析、会话统计和上游尝试四类数据;任务完成前不会提供部分文件。
导出以任务处理时的数据为准,新产生的记录可能不在本次文件中;需要最新记录时请重新导出。文件仅限本人及当前工作区成员权限访问,24 小时后过期;单文件最多 100,000 行或 16 MiB,每账户最多两项并行任务、每天二十项新任务。超过上限请缩小查询范围。
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 生命周期与存量治理
在 API Keys 或 Management Keys 中设置账户和工作区期限上限,两层取更短值。账户层由组织管理员管理,工作区层由该工作区管理员管理。策略保存只约束之后新建和轮换的凭据。
选择最多 100 个存量 Key,预览应用当前期限或批量停用。预览有效期为 5 分钟,执行时再次核对当前个人会话、管理员权限、策略和所选凭据;任何变化都要求重新预览。期限从 secret 发放时刻计算,不会延长已有期限;发放时间不明的凭据需轮换。收紧时撤销宽限期旧密钥,在途请求仍可完成结算。
可在通知中查看即将到期和最近过期的密钥,并在通知偏好订阅邮件提醒。请在到期前轮换并更新应用配置;系统不会自动替你轮换密钥。
组织管理员还可在“组织管理 → 密钥治理”跨活跃工作区查看 Key 风险,按到期、复核和期限不合规筛选,并选择多个工作区的 Key 生成统一预览。批量执行要求当前仍拥有每个所选工作区的管理员权限;刷新后可以恢复未完成预览或已提交回执。隐私影响报告会合并账户、工作区、Key 和护栏限制,只评估静态端点资格,不保存策略或调用供应商。
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保护账户和密钥
开启认证器验证,私密保存恢复码,定期检查登录会话。为不同应用分别创建推理密钥,并设置合适的模型权限、预算和有效期。密钥只保存在应用的受保护配置中,不要放进公开网页、代码仓库、截图或聊天消息。
完整密钥仅在创建或轮换时显示。发现泄露后立即停用或轮换,并更新应用配置;退出网页登录不会自动停用 API 密钥。工作区管理员还可设置密钥有效期及隐私策略。
遵守供应商条款
你有责任遵守各供应商的定价、区域限制、数据义务以及适用的税务和开票要求。