NcatBot 文档

外观

AI API 参考

约 1702 字大约 6 分钟

2026-03-21

AI 平台 Bot API 完整签名参考 — Chat Completion / Embeddings / Image Generation。

Quick Reference

# 通过 BotAPIClient 访问
api.ai.chat(...)
api.ai.embeddings(...)
api.ai.image_generation(...)
api.ai.video_generation(...)
api.ai.video_status(...)
api.ai.video_content(...)
api.ai.transcription(...)

# Sugar 便捷方法
api.ai.chat_text(...)          # → str
api.ai.generate_image(...)     # → Image 消息段
api.ai.transcription_text(...) # → str
BotAPIClient
└── .ai : IAIAPIClient (AIBotAPI)
    ├── chat()              ← Chat Completion → ModelResponse
    ├── chat_text()         ← Chat Completion → str
    ├── embeddings()        ← 文本向量化
    ├── image_generation()  ← 图像生成 → ImageResponse
    ├── generate_image()    ← 图像生成 → Image 消息段
    ├── video_generation()  ← 视频生成任务 → VideoObject
    ├── video_status()      ← 视频任务查询 → VideoObject
    ├── video_content()     ← 视频下载 → bytes
    ├── transcription()     ← 语音识别 → TranscriptionResponse
    └── transcription_text()← 语音识别 → str

接口定义

from ncatbot.api.ai import IAIAPIClient

IAIAPIClient 继承自 IAPIClient

属性/方法类型说明
platformstr固定返回 "ai"
call(action, params)async通用调用入口
chat(...)asyncChat Completion → ModelResponse
chat_text(...)asyncChat Completion → str (sugar)
embeddings(...)async文本向量化
image_generation(...)async图像生成 → ImageResponse
generate_image(...)async图像生成 → Image 消息段 (sugar)
video_generation(...)async视频生成 → VideoObject，见 视频 API
video_status(...)async视频任务状态查询 → VideoObject
video_content(...)async下载已完成的视频 → bytes
transcription(...)async语音识别 (ASR) → TranscriptionResponse
transcription_text(...)async语音识别 (ASR) → str (sugar)

chat()

async def chat(
    content_or_messages: str | list[dict] | MessageArray | MessageSegment,
    *,
    model: str | None = None,
    temperature: float | None = None,
    max_tokens: int | None = None,
    nickname_map: dict[str, str] | None = None,
    mcp_servers: dict[str, dict] | None = None,
    max_tool_calls: int = 10,
    **kwargs,
) -> ModelResponse

参数

参数类型必需说明
content_or_messagesstr | list[dict] | MessageArray | MessageSegment✅str 自动包装；list[dict] 透传；MessageArray / MessageSegment 自动转换
modelstr❌覆盖 completion_model，不存在时回退
temperaturefloat❌采样温度（0.0–2.0）
max_tokensint❌最大生成 token 数，覆盖 config 的 max_tokens
nickname_mapdict[str, str]❌At 段昵称映射，如 {"12345": "小明"}，缺省显示为 @user_id
mcp_serversdict[str, dict]❌MCP 服务器配置，缺省使用 config 的 mcp_servers；为空不启用工具。格式见 AI 适配器指南 § MCP 工具调用
max_tool_callsint❌单轮最多工具调用轮数（默认 10），防死循环
**kwargs❌透传给 litellm.acompletion() 的其他参数

MCP 工具调用

配置 mcp_servers 后，chat() 自动加载 MCP 工具并进入工具调用循环：模型请求工具 → 执行 MCP 工具 → 回传 role: "tool" 消息 → 继续对话，直到模型不再请求工具或达到 max_tool_calls 上限。

# 使用 config 中的 mcp_servers
resp = await api.ai.chat("查一下北京的天气")

# 临时覆盖服务器配置
resp = await api.ai.chat(
    "查一下北京的天气",
    mcp_servers={"weather": {"transport": "http", "url": "https://mcp.weather.com/mcp"}},
)

多服务器工具名按 {服务器名}_{工具名} 命名空间区分，避免同名冲突。finish_reason 为 "tool_calls" 时表示模型请求了工具（已被适配器自动处理）。

MessageArray 转换规则

消息段转换结果
PlainText{"type": "text", "text": ...}
Image{"type": "image_url", "image_url": {"url": ...}}，base64:// 自动转 data URI
At@{user_id} 或 @{nickname}（依据 nickname_map）
Reply[回复消息 id=...]
Video / File / Record跳过 + 警告日志
其他（Face 等）跳过 + 警告日志

纯文本 MessageArray 自动优化为普通 str content；含图片时使用多模态 list 格式。

返回值：ModelResponse

class ModelResponse:
    id: str                      # 请求唯一标识，如 "chatcmpl-xxx"
    choices: list[Choices]       # 生成结果列表
    created: int                 # Unix 时间戳
    model: str                   # 实际使用的模型名
    usage: Usage                 # Token 用量统计
    system_fingerprint: str | None

class Choices:
    finish_reason: str           # "stop" | "length" | "tool_calls"
    index: int                   # 结果索引
    message: Message             # 生成的消息

class Message:
    content: str | None          # 生成的文本内容
    role: str                    # "assistant"
    reasoning_content: str | None  # 推理内容（部分模型支持）

class Usage:
    prompt_tokens: int           # 输入 token 数
    completion_tokens: int       # 输出 token 数
    total_tokens: int            # 总 token 数

快速取值

resp = await api.ai.chat("你好")
resp.choices[0].message.content   # → "你好！有什么可以帮你的？"
resp.usage.total_tokens           # → 30
resp.model                        # → "gpt-4"

embeddings()

async def embeddings(
    input_text: str | list[str],
    *,
    model: str | None = None,
    **kwargs,
) -> EmbeddingResponse

参数

参数类型必需说明
input_textstr | list[str]✅待嵌入的文本或文本列表
modelstr❌覆盖 embedding_model，不存在时回退
**kwargs❌透传给 litellm.aembedding()

返回值：EmbeddingResponse

class EmbeddingResponse:
    model: str                   # 模型名
    data: list[Embedding]        # 嵌入结果列表
    usage: Usage                 # Token 用量

class Embedding:
    embedding: list[float]       # 向量
    index: int                   # 在输入列表中的索引

快速取值

resp = await api.ai.embeddings("Hello world")
resp.data[0].embedding           # → [0.1, -0.2, 0.3, ...]
len(resp.data[0].embedding)      # → 1536 (取决于模型)

image_generation()

async def image_generation(
    prompt: str,
    *,
    model: str | None = None,
    size: str | None = None,
    **kwargs,
) -> ImageResponse

参数

参数类型必需说明
promptstr✅图像描述文本
modelstr❌覆盖 image_model，不存在时回退
sizestr❌图像尺寸，如 "1024x1024", "512x512"
**kwargs❌透传给 litellm.aimage_generation()

返回值：ImageResponse

class ImageResponse:
    created: int                 # Unix 时间戳
    data: list[ImageObject]      # 图像结果列表

class ImageObject:
    url: str | None              # 图片 URL
    b64_json: str | None         # Base64 编码的图片数据
    revised_prompt: str | None   # 修正后的提示词

快速取值

resp = await api.ai.image_generation("一只猫", size="1024x1024")
resp.data[0].url                 # → "https://..."

模型回退机制

聊天、向量化、图片生成、视频生成与语音识别共享以下回退逻辑。 视频查询和下载按任务 ID 路由，不参与模型回退。

  1. 优先使用调用时传入的 model= 参数
  2. 若未传，使用 config 中对应功能的默认模型（completion_model / embedding_model / image_model / video_model / asr_model）
  3. 若指定的模型不存在（API 返回 model not found 类错误），自动回退到 config 中的默认模型
  4. 若默认模型也不存在，抛出原始异常
# config: completion_model = "gpt-4"

await api.ai.chat("hi", model="gpt-4-turbo")
# 1. 尝试 gpt-4-turbo
# 2. 若 gpt-4-turbo 不存在 → 回退到 gpt-4
# 3. 若 gpt-4 也不存在 → 抛出异常

call() 通用入口

async def call(action: str, params: dict | None = None) -> Any

通过 action 名路由到对应方法：

await api.ai.call("chat", {"content_or_messages": "你好"})
# 等价于
await api.ai.chat("你好")

Sugar 便捷方法

chat_text()

async def chat_text(
    content_or_messages: str | list[dict] | MessageArray | MessageSegment,
    *,
    model: str | None = None,
    temperature: float | None = None,
    max_tokens: int | None = None,
    nickname_map: dict[str, str] | None = None,
    mcp_servers: dict[str, dict] | None = None,
    max_tool_calls: int = 10,
    **kwargs,
) -> str

参数与 chat() 完全相同（含 mcp_servers / max_tool_calls），直接返回 choices[0].message.content（str）。 content 为 None 时返回空字符串。

# 字符串输入
text = await api.ai.chat_text("你好")
# → "你好！有什么可以帮你的？"

# 直接传入事件消息（图文混合）
text = await api.ai.chat_text(event.message)

# 带昵称映射
text = await api.ai.chat_text(event.message, nickname_map={"12345": "小明"})

generate_image()

async def generate_image(
    prompt: str,
    *,
    model: str | None = None,
    size: str | None = None,
    **kwargs,
) -> Image

参数与 image_generation() 完全相同，直接返回 ncatbot.types.Image 消息段对象。 可直接放入 MessageArray 或作为 event.reply() 参数发送。

  • 有 URL 时：Image(file=url, url=url)
  • 仅有 b64_json 时：Image(file="base64://...")
image = await api.ai.generate_image("一只猫", size="1024x1024")
await event.reply(image)  # 直接发送图片

transcription_text()

async def transcription_text(
    file: Any,
    *,
    model: str | None = None,
    language: str | None = None,
    prompt: str | None = None,
    temperature: float | None = None,
    **kwargs,
) -> str

参数与 transcription() 相同（无 response_format），直接返回识别出的纯文本（str）。 text 为 None 时返回空字符串。

# 从文件路径
with open("audio.mp3", "rb") as f:
    text = await api.ai.transcription_text(file=f)
# → "大家好，欢迎来到今天的直播..."

# 配合 Bilibili 音频流
url = await api.bilibili.get_video_audio_url("BV1wa411Q7N6")
audio = await download(url)
text = await api.ai.transcription_text(file=audio)

延伸阅读

版权归属：GEYUANwuqi

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot