DOCS / V1.0
最后更新:2026-11-15 · 适用于摩杜云 Open API v1
5 分钟接入
先创建 API Key,再选择一个产品发起请求。测试与生产使用不同 Key,建议通过环境变量注入,不要写进前端代码。
01注册并认证创建企业账号,完成实名认证。
02创建 API Key在控制台创建 Key,区分测试 / 生产。
03选择产品短信、邮件、物流或 AI 大模型。
04发起请求按示例调用,查看 request_id 与响应。
第一个请求:AI 对话
curl https://api.moduyun.com/v1/chat/completions \
-H "Authorization: Bearer $MODU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'from openai import OpenAI
client = OpenAI(
base_url="https://api.moduyun.com/v1",
api_key=os.environ["MODU_API_KEY"],
)
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.moduyun.com/v1",
apiKey: process.env.MODU_API_KEY,
});
const resp = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);说明示例中的模型 ID 与参数以控制台模型广场为准;不同模型支持的能力可能不同。
鉴权与安全
所有 Open API 使用 Bearer Token。请在请求头携带 API Key,并在服务端调用;不要在前端、日志或代码仓库中暴露生产 Key。
Authorization: Bearer <YOUR_API_KEY>
测试 / 生产隔离为不同环境创建独立 Key,设置配额与回调地址。
最小权限按产品与项目授权,离职或轮换时及时禁用。
IP 白名单生产 Key 建议绑定固定出口 IP,降低泄露风险。
API 索引
| 产品 | 方法 | 路径 | 用途 |
|---|---|---|---|
| AI 大模型 | POST | /v1/chat/completions | 对话、流式输出、多模态输入 |
| AI 大模型 | GET | /v1/models | 列出可用模型与参数 |
| 短信 | POST | /v1/sms/send | 验证码、通知、营销短信 |
| 邮件 | POST | /v1/email/send | 事务邮件与批量发送 |
| 物流 | POST | /v1/logistics/query | 单号查询与批量查询 |
| 物流 | POST | /v1/logistics/subscribe | 订阅轨迹状态变更 |
AI 大模型 API
统一 Base URL 与 API Key,兼容 OpenAI SDK。通过 model 参数切换模型,业务代码不需要为每个厂商重写。
Base URLhttps://api.moduyun.com/v1
协议HTTPS / JSON / SSE 流式
鉴权Bearer Token
查询模型列表
curl https://api.moduyun.com/v1/models \ -H "Authorization: Bearer $MODU_API_KEY"
流式对话
在请求体设置 stream: true,服务端以 SSE 返回增量内容;客户端需处理断线重连与超时。
| DeepSeek | 通用对话、代码、推理 |
|---|---|
| Qwen | 中文、长上下文、多模态 |
| GLM / Kimi / MiniMax | 通用、长文本、角色与工具调用 |
| 豆包 | 中文对话与内容生成 |
模型差异上下文长度、视觉输入、工具调用与价格以模型广场标注为准;不要假设所有模型能力一致。
短信服务
发送前需完成签名与模板审核。验证码、通知与营销短信建议使用不同模板,并设置频率限制与退订策略。
POST /v1/sms/send
{"phone":"13800000000","template_id":"1001","params":["123456"]}
响应包含 request_id 与状态;失败时按错误码与回执排查,不要仅依赖“已提交”。
邮件推送
支持邮件 API 与 SMTP 两种接入方式。自定义发信域名需配置 SPF、DKIM 与 DMARC;事务邮件与营销邮件建议使用不同子域名。
邮件 APIPOST /v1/email/send,返回投递 ID 与状态。
SMTPsmtp.moduyun.com:465,SSL/TLS,使用独立凭证。
退订营销邮件必须包含退订链接,维护退订与黑名单。
物流查询
支持单号查询、批量查询与订阅推送。建议先做单号识别,再按承运商查询;状态变更通过 Webhook 回调,失败会重试。
POST /v1/logistics/query
{"waybill":"SF146890321176","carrier":"SF"}
回调验签Webhook 需校验签名并做幂等处理;返回 2xx 表示接收成功,超时或非 2xx 会重试。
错误码与限流
| 401 | Key 无效、过期或未携带 |
|---|---|
| 403 | 无权限、配额不足或 IP 不在白名单 |
| 404 | 资源不存在或路径错误 |
| 429 | 触发限流,按 Retry-After 退避重试 |
| 500 | 服务内部错误,携带 request_id 联系支持 |
建议为所有请求记录 request_id、状态码与耗时;重试使用指数退避,避免雪崩。
SDK 与工具
OpenAPI下载 OpenAPI 规范,生成客户端或导入调试工具。
SDKPython / Node.js / Go / Java 示例与鉴权封装。
调试台在控制台在线调试,查看请求与响应。
获取支持
接入、联调、回调验签或迁移遇到问题,可以提交工单或联系架构师。企业客户可获得 1:1 支持。
本页为静态演示文档,正式接入请以控制台下载的最新 OpenAPI 文档为准。
