SDK接口规范文档

版本：v1.1.0
唯一依赖：pip install requests
使用方式：将 moyuai/ 目录复制到项目中，from moyuai import MoyuAI

通用说明

所有 SDK 函数的返回值均包含 .status 字段（bool 类型），用于判断本次调用是否成功：

每个函数的文档分为三部分：

输入 — 调用时传入的参数

输出 — 返回对象中的业务数据字段

返回 — .status 字段，表示调用成功或失败

1. 初始化

SDK初始化，无需传入任何参数，同时，魔芋平台域名已内置。

2. 账务功能

所有账务函数通过 client.account.xxx() 调用。
需要先通过 temp_register() 或 login() 获得认证，认证后 SDK 自动保存凭证，后续调用无需再传认证参数。

2.1 临时注册

输入：

参数	类型	必填	说明
`appid`	int	否	智能体应用 ID，传入后自动绑定到默认令牌

输出：TempRegisterResult 对象

字段	类型	说明
`.user_id`	int	用户 ID
`.username`	str	随机用户名（`tmp_` 前缀）
`.password`	str	随机密码（仅此一次返回，需保存）
`.access_token`	str	账务接口认证凭证
`.api_key`	str	对话接口凭证（`sk-xxx` 格式）

返回：

字段	类型	说明
`.status`	bool	`True`=注册成功，`False`=注册失败

示例：

2.2 临时用户转正式用户

临时注册用户通过绑定手机号转为正式用户，绑定后可使用手机号 + 密码登录。

分两步调用：

输入：

参数	类型	必填	说明
`phone`	str	是	要绑定的手机号
`code`	str	否	6位短信验证码（不传则自动发送验证码）
`appid`	int	否	智能体应用 ID，绑定成功后自动绑定到默认令牌

输出：Result 对象

字段	类型	说明
`.message`	str	提示信息（发送验证码时返回"验证码已发送，请查收短信"）

返回：

字段	类型	说明
`.status`	bool	`True`=操作成功，`False`=操作失败

示例：

2.3 正式用户注册

分两步调用，无需手动发送验证码：

输入：

参数	类型	必填	说明
`phone`	str	是	手机号
`password`	str	第二步必填	密码（8-20字符，发送验证码时无需传入）
`verification_code`	str	否	6位短信验证码（不传则自动发送验证码）
`email`	str	否	邮箱
`username`	str	否	用户名（默认用手机号）
`aff_code`	str	否	邀请码
`appid`	int	否	智能体应用 ID，传入后自动绑定到默认令牌

输出：Result 对象

字段	类型	说明
`.message`	str	提示信息（发送验证码时返回"验证码已发送，请查收短信"）

返回：

字段	类型	说明
`.status`	bool	`True`=操作成功，`False`=操作失败

示例：

2.4 用户登录

输入：

参数	类型	必填	说明
`username`	str	是	用户名、手机号或邮箱（三者任一均可）
`password`	str	是	密码

输出：LoginResult 对象

字段	类型	说明
`.user_id`	int	用户 ID
`.username`	str	用户名
`.display_name`	str	显示名称
`.user_status`	int	用户状态：1=启用, 2=禁用
`.access_token`	str	认证凭证

返回：

字段	类型	说明
`.status`	bool	`True`=登录成功，`False`=登录失败

示例：

2.5 查询余额

输入： 无参数。

输出：Balance 对象

字段	类型	说明
`.username`	str	用户名
`.phone`	str	手机号
`.balance_yuan`	float	当前剩余额度（人民币元）
`.used_yuan`	float	历史消耗额度（人民币元）
`.topup_yuan`	float	历史充值额度（人民币元）
`.request_count`	int	总请求次数

返回：

字段	类型	说明
`.status`	bool	`True`=查询成功，`False`=查询失败

示例：

2.6 充值

支持两种充值方式：兑换码充值和在线支付。

前置条件： 充值前 SDK 会自动检查用户是否已绑定手机号（正式用户）。临时用户需先调用 bind_phone() 绑定手机号后才能充值，否则抛出 MoyuAIError 异常。

方式一：兑换码充值

输入：

参数	类型	必填	说明
`key`	str	是	兑换码

输出：TopupResult 对象

字段	类型	说明
`.message`	str	提示信息
`.added_yuan`	float	本次充值金额（单位：元）

返回：

字段	类型	说明
`.status`	bool	`True`=充值成功，`False`=充值失败

示例：

方式二：在线支付（支付宝/微信）

调用后自动打开浏览器支付页面，等待用户完成支付，支付成功后返回充值记录。

输入：

参数	类型	必填	说明
`amount`	int	是	充值金额（元）
`payment_method`	str	是	支付方式：`alipay`（支付宝）或 `wxpay`（微信）
`timeout`	int	否	最长等待时间（秒），默认 180
`poll_interval`	int	否	轮询间隔（秒），默认 3

输出：TopUpRecord 对象

字段	类型	说明
`.amount`	int	充值金额（元）
`.money`	float	实际支付金额（元）
`.trade_no`	str	订单号
`.payment_method`	str	支付方式
`.pay_status`	str	支付状态：`success`=已完成, `pending`=待支付
`.create_time`	int	创建时间（Unix 时间戳）
`.complete_time`	int	完成时间

返回：

字段	类型	说明
`.status`	bool	`True`=调用成功，`False`=调用失败

超时未支付将抛出 MoyuAIError 异常，异常信息中包含订单号。

示例：

2.7 查询账单

默认查询今天 00:00:00 到当前时间的全部记录（消费+充值），无需传时间参数。返回最新记录，上限 500 条。

输入：

参数	类型	必填	说明
`model_name`	str	否	按模型名称过滤
`token_name`	str	否	按令牌名称过滤
`start_time`	int	否	开始时间（Unix 时间戳秒），默认今天 00:00:00
`end_time`	int	否	结束时间（Unix 时间戳秒），默认当前时间
`bill_type`	str	否	账单类型：`"consume"`=消费，`"topup"`=充值，不传则返回全部

输出：BillResult 对象

字段	类型	说明
`.total`	int	时间范围内总记录数
`.bills`	list[BillRecord]	账单列表（最多 500 条）

每个 BillRecord 包含：

字段	类型	说明
`.time`	str	记录时间（`2026-03-12 14:30:00` 格式）
`.model`	str	使用的模型名称
`.prompt_tokens`	int	输入 token 数
`.completion_tokens`	int	输出 token 数
`.cost_yuan`	float	金额（人民币元）
`.token_name`	str	使用的令牌名称
`.use_time_ms`	int	请求耗时（毫秒）

返回：

字段	类型	说明
`.status`	bool	`True`=查询成功，`False`=查询失败

示例：

2.8 查看令牌

输入：

参数	类型	必填	说明
`page`	int	否	页码，默认 1
`page_size`	int	否	每页条数，默认 10

输出：TokensResult 对象

字段	类型	说明
`.items`	list[TokenInfo]	令牌列表

每个 TokenInfo 包含：

字段	类型	说明
`.id`	int	令牌 ID
`.name`	str	令牌名称
`.key`	str	API Key（`sk-xxx` 格式）
`.token_status`	int	令牌状态：1=启用, 2=禁用, 3=已过期, 4=额度耗尽
`.remain_yuan`	float	剩余额度（单位：元）
`.used_yuan`	float	已用额度（单位：元）
`.unlimited_quota`	bool	是否无限额度
`.expired_time`	int	过期时间（-1=永不过期）
`.created_time`	int	创建时间（Unix 时间戳）
`.appid`	int	绑定的智能体应用 ID（0表示未绑定）
`.group`	str	令牌所属分组（空字符串表示默认分组）

返回：

字段	类型	说明
`.status`	bool	`True`=查询成功，`False`=查询失败

示例：

2.9 创建令牌

输入：

参数	类型	必填	说明
`name`	str	是	令牌名称（最长 50 字符）
`remain_yuan`	float	否	令牌额度（单位：元，`unlimited_quota=False` 时生效）
`unlimited_quota`	bool	否	是否无限额度，默认 True
`expired_time`	int	否	过期时间（Unix 时间戳，-1=永不过期），默认 -1
`model_limits_enabled`	bool	否	是否启用模型限制，默认 False
`model_limits`	str	否	允许的模型列表（逗号分隔）
`appid`	int	否	智能体应用 ID
`group`	str	否	分组名称（不传则使用默认分组，可通过 `get_groups()` 查看可用分组）

输出：Result 对象

字段	类型	说明
`.message`	str	提示信息

返回：

字段	类型	说明
`.status`	bool	`True`=创建成功，`False`=创建失败

创建后通过 get_tokens() 获取新令牌的 key。

2.10 更新令牌

输入：

参数	类型	必填	说明
`id`	int	是	令牌 ID
`name`	str	否	新名称
`status`	int	否	1=启用, 2=禁用
`remain_yuan`	float	否	令牌额度（单位：元）
`unlimited_quota`	bool	否	是否无限额度
`expired_time`	int	否	过期时间
`model_limits_enabled`	bool	否	是否启用模型限制
`model_limits`	str	否	允许的模型列表
`appid`	int	否	智能体应用 ID（传0可清除绑定）
`group`	str	否	分组名称（传空字符串可清除分组回到默认）

注意：输入参数中的 status 是传给服务端的令牌启用/禁用状态（int），与返回值中的 .status（bool，表示调用是否成功）含义不同。

输出：UpdateTokenResult 对象

字段	类型	说明
`.data`	dict	更新后的完整令牌信息

返回：

字段	类型	说明
`.status`	bool	`True`=更新成功，`False`=更新失败

示例：

2.11 删除令牌

输入：

参数	类型	必填	说明
`id`	int	是	令牌 ID

输出：Result 对象

字段	类型	说明
`.message`	str	提示信息

返回：

字段	类型	说明
`.status`	bool	`True`=删除成功，`False`=删除失败

示例：

2.12 查看可用分组

输入： 无

输出：GroupsResult 对象

字段	类型	说明
`.items`	list[GroupInfo]	分组列表

每个 GroupInfo 包含：

字段	类型	说明
`.name`	str	分组名称（创建/更新令牌时传入的 group 参数值）
`.ratio`	any	分组倍率（数字或 "自动"）
`.desc`	str	分组描述

返回：

字段	类型	说明
`.status`	bool	`True`=查询成功，`False`=查询失败

示例：

3. 使用模型

认证方式：请求头 Authorization: Bearer <api_key>（api_key 通过 temp_register() 或 get_tokens().items 获取）。
基础地址：https://www.moyu.cn

3.1 获取模型列表

输入：

参数	类型	必填	说明
`api_key`	str	是	API Key（sk-xxx 格式）

输出：ModelsResult 对象

字段	类型	说明
`.items`	list[ModelInfo]	模型列表

每个 ModelInfo 包含：

字段	类型	说明
`.id`	str	模型名称（如 `claude-opus-4-6`）
`.object`	str	类型（固定为 `model`）
`.owned_by`	str	模型归属标识。命中内置映射时为供应商名（如 `openai`、`deepseek`、`coze`），未命中映射的模型统一返回 `custom`（如示例中的 `claude-opus-4-6`）
`.raw`	dict	API 原始返回的完整字段（预留，后续新增字段可直接从此取）

返回：

字段	类型	说明
`.status`	bool	`True`=查询成功，`False`=查询失败

示例：

3.2 文本对话

POST /v1/chat/completions

兼容 OpenAI Chat Completions 格式，支持所有文本模型。

Python 示例：

主要参数：

参数	类型	必填	说明
model	string	是	模型名称，如 `gpt-4o`、`claude-opus-4-6`、`deepseek-v3` 等
messages	array	是	对话消息列表，每条包含 `role`（system/user/assistant）和 `content`
stream	bool	否	是否流式输出，默认 false
temperature	number	否	采样温度 0-2，默认 1
max_tokens	int	否	最大生成 token 数

响应格式：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "你好！有什么可以帮你的？"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

3.3 图片生成

POST /v1/images/generations

使用豆包 Seedream 模型生成图片。

Python 示例：

主要参数：

参数	类型	必填	说明
model	string	是	固定为 `doubao-seedream-4-5-251128`
prompt	string	是	图片描述提示词
size	string	否	图片尺寸，如 `2K`、`2048x2048`、`2848x1600`，默认 2K
quality	string	否	`standard`(标准) 或 `hd`(高清)，默认 standard
response_format	string	否	`url`(返回链接) 或 `b64_json`(返回 Base64)

响应格式：

{
  "model": "doubao-seedream-4-5-251128",
  "created": 1770558368,
  "data": [
    {"url": "https://...", "size": "2048x2048"}
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}

3.4 视频生成

视频生成为异步接口，提交任务后通过轮询获取结果。

视频生成

POST /v1/video/generations

Python 示例（文生视频）：

图生视频示例：

提交任务参数：

参数	类型	必填	说明
model	string	是	模型名称，见下方列表
prompt	string	是	视频内容描述
images	string[]	图生视频时必填	输入图片 URL 数组
duration	int	否	视频时长（秒），默认 5

支持的模型：

模型名称	说明
doubao-seedance-1-5-pro-251215	Seedance 1.5 Pro（推荐）
doubao-seedance-1-5-lite-t2v-250428	Seedance 1.5 Lite 文生视频
doubao-seedance-1-5-lite-i2v-250428	Seedance 1.5 Lite 图生视频
doubao-seedance-1-0-pro-250528	Seedance 1.0 Pro
doubao-seedance-1-0-lite-t2v	Seedance 1.0 Lite 文生视频
doubao-seedance-1-0-lite-i2v	Seedance 1.0 Lite 图生视频

提交任务响应：

{"task_id": "cgt-20260211145453-2v7p2"}

查询结果

GET /v1/video/generations/{task_id}

使用提交任务返回的 task_id 轮询查询，直到视频生成完成。

异常说明

所有函数在失败时抛出异常，可统一捕获处理：

异常类	触发条件
`MoyuAIError`	基础异常（所有异常的父类）
`AuthenticationError`	认证失败（API Key 无效、未登录）
`RateLimitError`	请求频率超限
`InsufficientQuotaError`	额度不足
`APIError`	其他 API 错误

通用说明#

1. 初始化#

2. 账务功能#

2.1 临时注册#

2.2 临时用户转正式用户#

2.3 正式用户注册#

2.4 用户登录#

2.5 查询余额#

2.6 充值#

方式一：兑换码充值#

方式二：在线支付（支付宝/微信）#

2.7 查询账单#

2.8 查看令牌#

2.9 创建令牌#

2.10 更新令牌#

2.11 删除令牌#

2.12 查看可用分组#

3. 使用模型#

3.1 获取模型列表#

3.2 文本对话#

3.3 图片生成#

3.4 视频生成#

视频生成#

查询结果#

异常说明#

通用说明

1. 初始化

2. 账务功能

2.1 临时注册

2.2 临时用户转正式用户

2.3 正式用户注册

2.4 用户登录

2.5 查询余额

2.6 充值

方式一：兑换码充值

方式二：在线支付（支付宝/微信）

2.7 查询账单

2.8 查看令牌

2.9 创建令牌

2.10 更新令牌

2.11 删除令牌

2.12 查看可用分组

3. 使用模型

3.1 获取模型列表

3.2 文本对话

3.3 图片生成

3.4 视频生成

视频生成

查询结果

异常说明