模型 API

本页说明 Genesis 模型推理 API 的接入方式、接口列表及各接口的请求参数与响应字段。接口兼容 OpenAI 协议约定；创建密钥、控制台代码生成与用量查看见指南 · Genesis。

错误与限流见错误码；系统内置模型见系统模型库。

路径、字段名与默认值以控制台「使用」页接入信息及实际接口返回为准。部分接口（如重排序、文档识别、视频生成）在 OpenAI 协议中无统一标准，实现细节以线上为准。

接入信息

基础地址

在 Genesis 控制台「使用」页获取 Base URL。示意形态（域名与路径段以控制台为准）：

https://moi.matrixorigin.cn/taas/v1

路径拼接

规则	说明
版本段	Base URL 通常已包含 /v1
请求地址	Base URL + 下表「路径」列（例如路径为 /chat/completions）
注意	勿在已含 /v1 的 Base URL 上再次拼接 /v1，避免出现重复版本段

下文各表中的路径均相对于已含版本段的 Base URL。

认证方式

采用与 OpenAI 一致的请求头鉴权：

Authorization: Bearer <API_KEY>

• 使用官方 OpenAI SDK 时：将 api_key 设为 Genesis API Key，将 base_url 设为上述 Base URL。

• API Key 在 Genesis 密钥管理中创建；密钥可绑定可用模型、速率与额度。请勿将密钥写入代码仓库。

协议兼容

项	说明
请求字段	如 model、messages、temperature、stream 等沿用 OpenAI 语义
响应结构	如 choices、usage、data 等沿用 OpenAI 常见结构
SDK	官方 openai SDK（Python / Node.js 等）通过覆盖 base_url 与 api_key 即可调用

接口一览

接口	方法	路径	说明	计费维度
对话补全	POST	/chat/completions	文本对话与生成；支持多模态消息（图像输入）	Token（含图像折算）
文本嵌入	POST	/embeddings	文本向量化	Token
文档重排序	POST	/rerank	候选文档相关性排序	Token
文档识别	POST	/ocr	按页文档 / 图像识别	页数
图像生成	POST	/images/generations	根据文本生成图像	张数
视频生成	POST	/videos/generations	根据文本或图像生成视频	秒数
语音合成	POST	/audio/speech	文本转语音	字符数
语音识别	POST	/audio/transcriptions	语音转文本	时长（分钟）
模型列表	GET	/models	查询当前密钥可用的模型	—

说明：

• 视觉理解、带图对话优先使用对话补全的多模态消息体；文档识别用于传统按页 OCR。

• 控制台代码生成器当前覆盖的接口范围，以及 Responses、Messages 等扩展接口，以接入应用 为准；本页以参数速查为主。

---

对话补全

项	值
方法	POST
路径	/chat/completions

请求参数

参数	类型	说明	默认值
model	string	模型 ID，可在模型列表或模型广场获取	—
messages	array	消息列表。每条含 role（system / user / assistant）与 content（文本或多媒体数组）	—
temperature	number	采样温度，取值范围约 0–2	0.7
max_tokens	integer	最大生成 Token 数	模型默认
stream	boolean	是否以 SSE 流式返回	false
top_p	number	核采样，取值范围 0–1	0.9
frequency_penalty	number	频率惩罚，约 −2–2	0
presence_penalty	number	存在惩罚，约 −2–2	0
seed	integer	随机种子；固定后相同输入可复现输出	随机

响应字段

字段	说明
choices[0].message.content	模型回复正文
choices[0].finish_reason	stop 表示正常结束；length 表示达到 max_tokens
usage.prompt_tokens	输入 Token
usage.completion_tokens	输出 Token
usage.total_tokens	合计 Token，用于计费对账

stream 为 true 时，响应为多条 data: 事件，增量内容位于 choices[0].delta.content，结束标记为 data: [DONE]。

多模态消息

在同一接口中，可将 user 消息的 content 设为数组，混合文本与图像：

[
  {"type": "text", "text": "描述这张图"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
]

image_url.url 支持公网 URL 或 data:image/jpeg;base64,... 形式。prompt_tokens 可能包含按分辨率折算的图像 Token。

请求示例

POST {Base URL}/chat/completions
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "model": "<model_id>",
  "messages": [
    {"role": "system", "content": "你是一个严谨的数据助手。"},
    {"role": "user", "content": "解释什么是数据血缘。"}
  ],
  "temperature": 0.7,
  "stream": false
}

---

文本嵌入

项	值
方法	POST
路径	/embeddings

请求参数

参数	类型	说明
model	string	嵌入类模型 ID
input	string 或 array	单条文本或文本数组

响应字段

字段	说明
data[].embedding	向量，维度由模型决定
data[].index	对应批量输入中的下标
usage.total_tokens	计费用量

---

文档重排序

项	值
方法	POST
路径	/rerank

本接口在 OpenAI 协议中无统一标准定义，字段名称与路径以实际接口为准。

请求参数

参数	类型	说明
model	string	重排序类模型 ID
query	string	查询文本
documents	array	候选文档字符串列表
top_n	integer	返回前 N 条；缺省可返回全部
return_documents	boolean	是否在结果中返回原文；缺省 true

响应字段

字段	说明
results[]	按相关性降序排列
results[].index	对应请求中 documents 的下标
results[].relevance_score	相关性得分，常见范围为 0–1
results[].document.text	原文（return_documents 为 true 时）
usage.total_tokens	计费用量（若返回）

---

文档识别

项	值
方法	POST
路径	/ocr

用于按页文档或图像文字识别。视觉对话类需求请优先使用对话补全的多模态消息。

请求参数

参数	类型	说明
model	string	文档识别类模型 ID
image_url / image_base64	string	待识别资源；具体字段名以接口为准
format	string	输出格式，如 text、json（含坐标）、markdown；缺省 text

响应字段

字段	说明
text	识别全文
blocks[]	format 为 json 时的分块结果（如坐标、置信度）
usage.pages	计费页数

---

图像生成

项	值
方法	POST
路径	/images/generations

请求参数

参数	类型	说明
model	string	图像生成类模型 ID
prompt	string	文本提示
size	string	输出尺寸，如 512x512、1024x1024、1280x720、1536x1024
n	integer	生成张数，常见范围 1–4，缺省 1
negative_prompt	string	负向提示（若模型支持）
seed	integer	随机种子（若模型支持）

响应字段

字段	说明
data[].url	生成图像地址；可能具有时效，请及时转存
usage.images	计费张数

---

视频生成

项	值
方法	POST
路径	/videos/generations

该接口通常采用异步任务模式，提交后轮询或通过回调获取结果；约定以实际接口为准。

请求参数

参数	类型	说明
model	string	视频生成类模型 ID
prompt	string	文本提示
image_url	string	图生视频时使用的源图地址（若支持）
duration	integer	时长（秒），如 5、10、15
resolution	string	分辨率，如 720p、1080p

响应字段

字段	说明
id	任务标识
status	任务状态，如 queued、processing、succeeded、failed
video_url	成功后的视频地址
usage.seconds	计费秒数

---

语音合成

项	值
方法	POST
路径	/audio/speech

请求参数

参数	类型	说明
model	string	语音合成类模型 ID
input	string	待合成文本
voice	string	音色标识
format	string	音频格式，如 mp3、wav、opus
speed	number	语速，常见范围 0.5–2.0，缺省 1.0

响应说明

项	说明
响应体	多为音频二进制流，而非 JSON；Content-Type 随 format 变化
响应头	可能包含请求标识及计费字符相关字段，以实际接口为准

---

语音识别

项	值
方法	POST
路径	/audio/transcriptions

请求参数

参数	类型	说明
model	string	语音识别类模型 ID
file	file	音频文件（multipart），常见格式 mp3、wav、m4a
language	string	语言，如 zh、en、auto
response_format	string	输出格式，如 text、srt、json
timestamp	boolean	是否返回更细粒度时间戳（若支持）

响应字段

字段	说明
text	转写全文
language	识别语言
duration	音频时长（秒），用于按分钟计费
segments[]	response_format 为 json 时的分段信息

---

模型列表

项	值
方法	GET
路径	/models

无需请求体，请求须携带有效鉴权信息。

响应字段

字段	说明
data[].id	模型 ID，调用其它接口时填入 model
data[].type	模型类型
data[].status	可用性状态，如 normal、degraded、error

模型选型说明见系统模型库。

---

结果字段与计费用量

实现客户端时建议优先读取：

用途	常见位置
业务结果	message.content、embedding、url、text、results、音频流等
本次用量	usage 对象，或接口约定的专用响应头

接口	计费维度
对话补全、文本嵌入、文档重排序	Token
文档识别	页数
图像生成	张数
视频生成	秒数
语音合成	字符数
语音识别	时长（分钟）

单价与 Credit 规则见账户中心、Credit 与计费项与Genesis 用量与计费。