# 蜂巢 AI > 蜂巢 AI 是统一的大模型调用平台,提供文本、图片和视频生成能力。文档公开可读;实际调用需要 API 密钥,并按钱包余额计费。 本文件给 AI Agent 提供发现入口和最短接入路径。模型、参数、价格和可用状态以接口返回为准,不要从训练记忆或旧文档猜。 ## 先读 - [Agent 接入页](https://ai-hive.cn/platform/agent): 人看的接入向导和只读验证 - [Agent 接入说明](https://ai-hive.cn/api-guide.md): 文本、图片、视频和兼容协议的完整示例 - [OpenAPI 3.1](https://ai-hive.cn/api-docs/openapi.yaml): REST API 的机器可读定义 - [模型文档](https://ai-hive.cn/platform/docs): 参数、价格和请求示例;需要登录 - [密钥管理](https://ai-hive.cn/platform/keys): 创建和管理 API 密钥;需要登录 - [MCP 接入](https://ai-hive.cn/platform/mcp): 桌面智能体和本地 stdio 客户端;需要登录 - [REST API 接入](https://ai-hive.cn/platform/api): 按内容类型接入;需要登录 ## 鉴权与费用 - REST API 使用 `Authorization: Bearer $AI_HIVE_API_KEY`。 - MCP 使用 `AI_HIVE_MCP_KEY` 环境变量,不要把真实密钥写进公开配置。 - 读取账户、模型目录和模型详情不产生模型调用费用。 - 图片和视频先使用 `dryRun: true` 预检;正式生成才按当前价格计费。 - 价格、单位和适用条件必须从模型详情返回的 `pricingSnapshot` 读取。 ## 最短接入流程 1. 让用户在网页按接入方式创建 MCP 密钥或 API 密钥,并在运行环境设置 `AI_HIVE_MCP_KEY` 或 `AI_HIVE_API_KEY`。 2. 先调用 `get_user_info` 查询余额,再调用 `list_models` 读取模型目录。 3. 从 `list_models` 返回项选择 `publicModelId`;轻目录不包含线路、参数或价格明细。 4. 调用 `get_model`,根据 `routingModes` 选择线路,并读取 `paramsSchema`、媒体要求和 `pricingSnapshot`。 5. 图片或视频先 `dryRun: true`,确认参数和费用后再正式提交。 6. 正式提交使用稳定的 `clientRequestId`,重试时复用同一个标识和相同业务参数。 7. 文本调用可能超过宿主等待时间时,改用 `submit_chat_text` 或 `POST /chat/text/tasks`,再按 `taskId` 查询;图片、视频收到任务 ID 后用 `get_generation_task` 查询结果,不要重复创建任务。 ## MCP 本地 MCP 包当前发布版为 `@infimind-next/ai-hive-mcp@0.6.1`,使用 stdio 传输;任务工具以实际连接后的 `tools/list` 和客户端版本为准。常见只读工具: - `get_user_info`:账户和余额 - `list_models`:筛选可用模型并返回 `publicModelId`,轻目录不含线路、参数或价格明细 - `get_model`:读取 `routingModes`、`paramsSchema`、媒体要求和 `pricingSnapshot` 常见执行工具: - `chat_text`:文本调用;默认同步返回 - `submit_chat_text`:宿主可能超时或断线恢复时提交持久文本任务,立即返回 `taskId` - `get_chat_text_task`:按 `taskId` 查询文本任务;`RUNNING` 时按 `retryAfterMs` 查询 - `list_recent_chat_text_tasks`:找回当前账号近期文本任务摘要 - `generate_image`:图片预检或生成 - `generate_video`:视频预检或生成 - `get_generation_task`:查询生成任务 不同客户端的工具名称以实际连接后返回的工具列表为准。不要把本地 MCP 和远程 MCP 的媒体工具混为一组。 ## REST API - `GET https://ai-hive.cn/api/openapi/v2/models`:读取轻量模型目录(ID、名称、类型和素材模式),不含线路、参数或价格;支持 `modelType`、`limit` 和 `cursor` - `GET https://ai-hive.cn/api/openapi/v2/models/{publicModelId}`:读取 `routingModes`、`paramsSchema`、媒体要求和 `pricingSnapshot` - `POST https://ai-hive.cn/api/openapi/v1/chat/text`:同步文本调用,支持 `stream: true` - `POST https://ai-hive.cn/api/openapi/v1/chat/text/tasks`:提交持久文本任务并立即返回 `taskId` - `GET https://ai-hive.cn/api/openapi/v1/chat/text/tasks/{taskId}`:查询文本任务状态和结果 - `GET https://ai-hive.cn/api/openapi/v1/chat/text/tasks?limit=10`:找回近期文本任务摘要 - `POST https://ai-hive.cn/api/openapi/v1/generation/image`:图片预检或生成 - `POST https://ai-hive.cn/api/openapi/v1/generation/video`:视频预检或生成 - `GET https://ai-hive.cn/api/openapi/v1/generation/tasks/{taskId}`:查询任务状态和结果 完整字段和错误结构见 OpenAPI。不要根据旧文档自行拼接模型 ID、价格或参数。 ## 只读验证 验证接通时只读取账户和模型目录: - MCP:先调用 `get_user_info` 和 `list_models` - REST API:先请求 `https://ai-hive.cn/api/openapi/v2/models?modelType=TEXT&limit=20` 不要用图片或视频生成来测试连通性。验证阶段不会创建付费任务。 ## 安全与恢复 - 不要把真实密钥放进 URL、代码、日志、聊天记录或公开仓库。 - 参数错误、余额不足或素材问题修正后,使用新的 `clientRequestId`。 - 网络中断、超时或接口返回结果未知时,先查询原任务和账单,不要自动重建付费任务。 - 价格变化后重新读取模型详情和 `pricingSnapshot`,不要沿用旧价格。 - 对用户只说明实际能力、费用、限制、结果和必要操作,不直接展示内部错误码、请求标识或上游细节。 - 重要结果以任务查询接口和接口实际返回为准,不要声称预检成功就能保证生成成功。 ## 使用规则 文档公开可读不等于所有用途均获授权。实际调用需遵守登录后的协议、钱包计费规则和模型供应商限制。遇到无法确认的能力、价格或可用状态时,停下来查询接口或让用户联系支持。