公共 AI 接口

本章的相对路径基于个人 Key 的 https://api.jusuanhub.com:10443/v1，或应用联网调试的 https://app-api.jusuanhub.com:10443/v1。两者使用各自的 Bearer 凭据，素材不能跨身份混用。正式应用使用平台注入地址与 RuntimeSession，见正式 Runtime 参考，尤其OCR/转写不能套用公网上传格式。

JSON 请求设置 Content-Type: application/json；multipart 由客户端生成boundary。下文的 model 均为目录返回的公开别名，不是工作负载名称。示例中的 MODEL_ALIAS 应替换为当前身份确实可调用的模型。

1. GET /openapi.json — 下载机器合同

不需要请求体，200为OpenAPI3.1 JSON（openapi/info/servers/paths/components）。?download=1 增加文件下载头。此接口不调用模型；不需要在每次业务请求前下载。应用中心的综合OpenAPI下载还包含正式应用和控制面，不能把两个文件当成相同接口集合。

curl --fail-with-body --silent --show-error "${API_BASE}/openapi.json?download=1" --output public-openapi.json

2. GET /services — 可调用服务与动态限制

认证：本章所选身份的Bearer。无正文；serviceKind 可选字符串，按能力类别过滤，例如 video_generation、embedding。200正文为 {"object":"list","data":[...]}，不是 items；SDK services() 才归一为 items。

{"object":"list","data":[{"id":"minimax-h3","object":"service","modelAlias":"minimax-h3","serviceDisplayName":"MiniMax H3","serviceKind":"video_generation","available":true,"endpoints":{"generations":"/v1/media/generations","inputAssets":"/v1/assets/input","jobs":"/v1/jobs/{jobId}","assets":"/v1/assets/{assetId}/content"}}]}

上例为精简结构示意，endpoint键与扩展合同以实际目录为准。目录被限流时按429/Retry-After退避；无服务时不要改用猜测的别名。

3. GET /models — OpenAI兼容模型列表

Bearer认证，无正文，无分页参数。200 {"object":"list","data":[{"id":"MODEL_ALIAS","object":"model","owned_by":"jusuan"}]}。id就是请求的model；媒体条目可附 mediaSpecContract。一个别名在目录中去重；它不是集群、实例或算力清单。SDK：models() 返回归一后的 items。

4. GET /audio/voices 与 GET /audio/voices/{voiceId}

两者使用Bearer，无正文。列表200为 object=list/data[]；详情200直接返回一个音色对象。voiceId从列表取得；不存在或不可见返回受控404。SDK对应 voices() 和 voice(voice_id)，列表归一为items。

{"voiceId":"voice_example","version":1,"displayName":"示例音色","primaryLanguage":"zh","supportedLanguages":["zh"]}

目录不公开模型绑定、审核、许可快照或底层Runtime信息。不要把这里的voiceId误当作每个TTS模型都支持的speaker参数；实际声音选择规则由模型合同决定。

5. POST /chat/completions — 对话与视觉理解

网关有文本和素材前置保护，默认text_chat单消息及总文字最多16000字符、最多20条消息；vision默认文字上限8000，具体发布能力可能更严格。多模态素材按视觉理解指南构造，不能传任意外部视频URL。

{"model":"MODEL_ALIAS","messages":[{"role":"user","content":"用三句话介绍这项服务。"}],"stream":false}

非流式200透传模型JSON，不额外包 data。常见字段：id/object/created/model，choices[].index/message.role/message.content/finish_reason，可选 usage.prompt_tokens/completion_tokens/total_tokens。工具调用和结构化结果仅在模型声明支持时出现。

{"id":"chat_example","object":"chat.completion","model":"MODEL_ALIAS","choices":[{"index":0,"message":{"role":"assistant","content":"示例回答。"},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":5,"total_tokens":17}}

流式为200 text/event-stream，按SSE帧读取，不能调用 .json()。首个data事件可早于推理完成；连接中断时已有文本不代表完整回答。模型支持时常见结束标记为 [DONE]，以当前模型合同为准。需要流式的HTTP应用使用流式客户端；SDK通用JSON快捷方法不能被当作逐token流式迭代器。

curl --no-buffer --fail-with-body -H "Authorization: Bearer ${API_TOKEN}" \
  -H 'Content-Type: application/json' "${API_BASE}/chat/completions" \
  --data '{"model":"MODEL_ALIAS","messages":[{"role":"user","content":"你好"}],"stream":true}'

400修正JSON/限制/采样字段；429等有界退避；504表示上游超时。普通同步对话没有自动安全重放保证，网络结果未知时不要无限自动重试。图像续写等模型可声明异步任务，不能套用普通choices解析。

6. POST /embeddings — 文本向量

model与input必填。input为string或string[]；去掉空白项后仍须非空，最多64项，每项8192 Unicode字符。输出维度由模型决定，不猜维度、不假设跨模型向量可直接比较。

{"model":"MODEL_ALIAS","input":["第一段文本","第二段文本"]}

200为上游JSON，常见 object/data[]/model/usage；data每项包含 index/embedding，embedding是number数组。index关联输入位置，不用响应数组排序猜对应关系。

{"object":"list","model":"MODEL_ALIAS","data":[{"object":"embedding","index":0,"embedding":[0.1,-0.2]}],"usage":{"prompt_tokens":4,"total_tokens":4}}

示例向量只展示形状，不代表真实维度。400包括错误input类型、空输入、数量/长度超限；模型或服务类型不符同样拒绝。SDK：embeddings(payload)，返回JSON而非专用向量DTO。批次失败不应静默丢弃输入。

7. POST /rerank — 候选重排

query和documents合计≤65536字符。空文档项会被网关计量校验忽略，但应用应在提交前处理空项并保存索引映射，不自行拆批后把不同批次分数当同一排序保证。

{"model":"MODEL_ALIAS","query":"如何创建视频？","documents":["媒体生成接口说明","应用版本发布说明"],"top_n":1}

200常见 results[].index/relevance_score，部分模型带document和usage，网关不统一重命名上游字段。索引指向原候选，分数是相关性而非概率。

{"results":[{"index":0,"relevance_score":0.93}]}

400包括空query、非法documents、数量/总长超限；404为不可见模型。SDK rerank(payload) 返回JSON。

8. POST /ocr — 文档识别

Content-Type为JSON，model必填。当前图片OCR主路径先上传图片，发送 input_image_asset_id，可选 pages/task。pages是计量页数，省略或非正值的计量缺省为1，不能据此认为任意模型都能识别任意PDF或执行指定页码。

{"model":"MODEL_ALIAS","input_image_asset_id":"input_document_image","pages":1,"task":"ocr"}

公网网关识别 image_asset_id/input_image_asset_id/document_asset_id 计量引用，但具体模型输入合同仍需满足；这不意味着三个字段可任意替换。不要混入文档解析的 input_document_asset_id。详细上传格式见文档识别指南。

200为所选OCR模型的原始JSON。常见文本/文字块/页结构可包含text、blocks、bbox或confidence，但没有一个对所有OCR模型强制的统一信封；请按该模型output schema读取。不会自动保存为个人作品。

{"text":"示例识别文字","blocks":[{"text":"示例识别文字","bbox":[0,0,100,20]}]}

这是形状示例，不是所有模型都保证返回bbox。400修正参数；模型拒绝素材时保留受控错误code/requestId，不把空结果当识别成功。SDK ocr(payload) 为JSON调用；正式应用使用不同的readUrl输入形式。

9. POST /audio/transcriptions — 语音转写

公网请求是multipart：model必填字符串、file必填且非空；model也可从query读取。文件≤25 MiB，允许MIME为audio/wav、audio/x-wav、audio/mpeg、audio/mp3、audio/mp4、audio/x-m4a、audio/webm、audio/ogg、audio/flac。空或octet-stream类型只有扩展名符合规则才接受。不要用H3参考音频的15 MiB规则替代ASR规则。

curl --fail-with-body -H "Authorization: Bearer ${API_TOKEN}" \
  -F 'model=MODEL_ALIAS' -F 'file=@speech.mp3;type=audio/mpeg' \
  "${API_BASE}/audio/transcriptions"

language/response_format等只在模型明确支持时追加。200通常为JSON的 text；可选language、duration、segments。分段通常含id/start/end/text，起止单位为模型输出的秒。非JSON输出只在模型允许并显式请求时处理。

{"text":"欢迎使用聚算平台。"}

缺model/file、空文件或不支持MIME返回400；大于25 MiB返回413 audio_file_too_large。SDK现有JSON快捷方法不能替代公网multipart上传，请按本节HTTP示例或使用httpx的files参数；已部署应用则使用JSON inputs[].readUrl，见正式Runtime参考。

10. POST /images/generations — 图像生成

model、prompt及所选模型的模式/规格必填；常用 generationMode/resolutionTier/orientation/imageCount/seed，编辑模型还需受控输入图片。只用模型合同声明的字段，不把所有模型的参数合并提交。

{"model":"MODEL_ALIAS","prompt":"白色背景上的简洁蓝色陶瓷杯","resolutionTier":"1k","orientation":"square","imageCount":1}

示例需要选择支持该规格的图像模型。部分服务同步返回结果，异步服务202返回 jobId/status/requestId；重放终态可能200。按服务的executionMode和响应结构判断，不能把所有200都解析为视频Job。SDK image_generation(payload, idempotency_key=...) 返回归一字典。

上传、完整字段、模型分支见图像生成指南；异步查询下载见媒体链路。幂等键与素材ID均由应用保留，超时不换键重新生成。

11. POST /audio/generations — 语音、音乐与音效

model必填，分支参数不同：

{"model":"MODEL_ALIAS","text":"欢迎使用聚算平台。","voiceMode":"text"}

异步受理202，之后查询job并下载音频结果；SDK audio_generation(payload, idempotency_key=...) 返回归一字典。格式、音色枚举与Foley示例见语音与音效生成指南。网络未知结果的处理与媒体链路一致，不能因为输出是音频就忽略幂等。

12. POST /documents/parse — 文档解析

{"model":"MODEL_ALIAS","input_document_asset_id":"input_pdf","page_range":{"start_page":1,"end_page":3},"preset":"hybrid-medium","language":"ch"}

202返回异步job，成功产物可能是解析结果/归档，不是视频MP4；按assets[].mimeType下载。SDK document(payload, idempotency_key=...)。详细上传、页数计量和下载见文档解析指南。非法页码/缺页数/素材类型错误应修正请求，不盲目重复解析。

13. 视频、预检、素材与任务接口

以下操作的完整字段、成功和错误响应及HTTP/Python样例已集中在媒体全链路，不在此重复另一套参数表：

GET /assets/input/{id}/content 是另一种接口：使用平台已签发URL中的短期 token，不是Bearer就能下载的通用素材查询。原样使用已授权URL，不自行拼token、不记录链接秘密；签名无效/过期为401 invalid_input_asset_token。不存在为404；图像/视频内容可能按Runtime兼容性处理，不应用它来校验永久原始文件。此路径没有用户申请任意签名的公开API。

14. 公共错误与调用诊断

公共错误含 code/message/requestId/retryable，可选details；上游错误或流中断还需按具体接口处理。401/403/受控404可能都来自身份不可用，不用状态码探测其它用户资源。402先处理余额，409区分服务冲突与幂等冲突，429按Retry-After有界退避，5xx不代表写入一定没发生。

{"code":"invalid_argument","message":"model is required","requestId":"req_example","retryable":false}

保存服务端requestId与应用业务ID关联；可发送 X-Client-Request-Id（可见ASCII、最多512字节），但它不替代服务端requestId或幂等键。应用中心HTTP、SDK、场景指南是同一接口合同的不同读法，不应凭示例里缺省的字段猜测业务上限。