OpenAPI 规范与工具

全部接口的机器可读描述（OpenAPI 3.1）：路径、请求体、每个状态码的响应、错误信封、枚举与默认值、鉴权方式。它就是这套接口的合同——文档页里的每一句都能在里面找到对应字段。

在浏览器里打开下载 JSON 文件https://api.maosika.com/v2/openapi.json

拿到它能做什么：接口工具一键导入（不用逐个手建请求）；一行命令生成你那门语言的客户端；把地址丢给 AI 编程助手，它读完就会写调用代码。

导进接口工具

所有主流工具都支持「按 URL 导入 OpenAPI」。地址填 https://api.maosika.com/v2/openapi.json，不需要登录、不需要 Key。

工具怎么导
Apifox项目 → 导入 → 「URL 导入」→ 数据格式选 OpenAPI/Swagger → 粘贴地址 → 导入。之后在「环境」里把 Authorization 设为 Bearer 你的 Key。
PostmanImport → 粘贴地址（或拖入下载的 JSON）→ Import。生成的 Collection 顶层 Authorization 选 Bearer Token 填一次 Key，所有请求继承。
InsomniaCreate → Import → From URL → 粘贴地址。鉴权同样在 Collection 的 Auth 里设 Bearer 一次。
Swagger Editoreditor.swagger.io → File → Import URL → 粘贴地址。纯浏览器工具，我们的规范已放开跨域，可直接在页面里「Try it out」。
VS Code / JetBrainsVS Code 装 「OpenAPI (Swagger) Editor」、JetBrains 自带 OpenAPI 支持：打开下载的 JSON 即可浏览与发请求。

导入后只剩一件事：在工具的鉴权设置里填 Bearer <你的 Key>（规范里已声明为 HTTP Bearer，工具会自动生成这一栏）。成片下载链接不需要鉴权，规范里对那个端点单独标了 security: []。

生成客户端代码

不想手写请求封装？按你的语言挑一行命令，从规范生成类型与客户端。

# TypeScript types only (zero runtime, works with fetch)
npx openapi-typescript https://api.maosika.com/v2/openapi.json -o maosika-video-api.d.ts

# or a full client via openapi-generator (needs Java)
npx @openapitools/openapi-generator-cli generate -i https://api.maosika.com/v2/openapi.json -g typescript-fetch -o ./maosika-client

喂给 AI 编程助手

用 Cursor / Claude Code / Codex / Copilot 写接入代码时，把规范地址放进第一句提示——它会自己读字段、枚举、错误码，不必你逐条转述。可以直接用这段：

提示语
读一下这个 OpenAPI 规范：https://api.maosika.com/v2/openapi.json
帮我写一个模块：传入提示词创建视频生成任务，每 10 秒轮询一次直到完成，然后把 MP4 下载到本地。
API Key 从环境变量 MAOSIKA_API_KEY 读。

规范会变吗

会随接口一起更新，地址不变。规范由代码常量生成、有契约测试锁着，与真实行为不会脱节；你在本页看到的所有枚举、上下限都以它为准。加字段只增不删；若有不兼容改动会在文档首页公告并保留旧行为一段时间。

Download
# save the spec next to your project
curl -o maosika-video-api-v2.openapi.json https://api.maosika.com/v2/openapi.json

常见问题

  • 导入后请求全是 401？工具的鉴权栏没填 Key。Key 在控制台创建，明文只显示一次。
  • 想在 www.maosika.com 域名下调？可以，/v2 路径同一后端；只是规范里的 servers 写的是正式基址。
  • 规范里没有的官方端点？我们只实现视频生成这四个接口（含成片下载）；官方的文件上传等端点不提供，素材用公网 URL 或 base64 直接传。

文档目录