# AI API Gateway Wiki > Canonical knowledge base for this deployment's AI API gateway concepts, integration guides, and access-control references. Use the current public URLs as the source of truth. Model availability, prices, and policies are deployment-specific and can change. ## AI API 网关 Canonical URL: /wiki/concepts/ai-api-gateway AI API 网关将不同上游模型服务聚合为一个统一入口，并在请求到达提供商前执行鉴权、模型选择、路由和用量治理。 定义：AI API 网关是位于调用方与多个模型提供商之间的控制层。调用方使用稳定的域名、凭据和兼容接口；网关根据部署配置完成转发与管理。 ### 它解决什么问题 不同模型提供商的认证方式、地址、请求格式、限额和计价规则并不相同。网关将这些差异收敛在服务端，让应用侧可以围绕一个基础地址和一组 API Key 集成。 网关并不等同于模型提供商。它负责选择和调用已配置的上游；某个模型能否使用仍取决于当前部署的通道、权限、余额和策略。 - 统一入口：调用方不需要为每个上游维护不同的域名与密钥。 - 协议适配：在支持的范围内将兼容请求转换为上游所需格式。 - 治理控制：在转发前执行鉴权、限流、配额与路由判断。 ### 一次请求如何流转 请求先到达公开 API 路径。身份校验通过后，系统根据模型、用户分组、令牌限制与通道状态筛选候选通道，再按配置的优先级、权重和重试规则处理。 上游响应会被转换回对调用方约定的响应形式；用量与日志则用于后续结算、审计和运维观察。这个流程使应用侧与上游变化保持相对解耦。 ### 使用边界 公开价格页和模型页反映的是当前部署公开展示的信息。不要把知识库中的概念说明理解为某一模型、价格或服务等级的永久承诺。 将网关接入生产环境前，应分别验证目标模型、鉴权方式、流式响应、超时策略以及账户或 Key 的配额限制。 ## 通道与路由 Canonical URL: /wiki/concepts/channels-and-routing 通道代表一个可用的上游连接；路由是在多个候选通道之间，依据模型、权限、健康状态、优先级和权重选择实际执行者的过程。 定义：通道保存上游类型、地址、密钥和可用模型等连接信息。路由只在满足访问规则的候选通道中进行，并不绕过权限或令牌限制。 ### 通道是上游连接的单位 一个通道通常对应某个提供商账号、代理或兼容服务地址。它包含连接配置以及允许转发的模型范围；实际字段和可用能力依赖通道类型。 将同一提供商拆分为多个通道可以隔离凭据、地区、预算或工作负载。管理端应将密钥保留在通道配置中，而不是交给终端应用。 ### 候选集先于负载分配 系统会先按请求模型、用户或令牌允许范围、分组和可用状态筛选候选通道。随后才会应用优先级、权重、健康检查、重试或切换等策略。 因此，提高某个通道的权重不会让它突破模型限制或用户的通道白名单。排查“为什么没有命中某通道”时，应先检查候选条件，再检查分配策略。 - 模型匹配决定通道能否处理该请求。 - 权限和令牌约束决定请求是否能进入该通道。 - 优先级、权重和健康状态决定候选之间的选择顺序。 ### 运营建议 为关键模型保留多个可替代通道，并通过实际请求验证不同协议、流式输出与媒体能力。健康状态只能反映已检测到的连接状况，不能替代对业务请求的端到端测试。 ## API Key、配额与访问控制 Canonical URL: /wiki/concepts/api-keys-and-access API Key 是调用 AI 中继接口的凭据；用户登录态、Access Token 和 API Key 的用途不同，配额与模型或通道限制共同决定实际访问范围。 定义：API Key（通常以 sk- 开头）面向模型调用。它不是管理后台登录凭据，也不应被用于读取用户钱包、管理 Key 或执行管理员操作。 ### 区分三种身份凭据 浏览器登录态或 Access Token 用于用户与管理类 API，例如查看账户、管理 API Key。API Key 用于 AI 中继请求，并可在部署启用兼容接口时查询该 Key 自身的用量。 这种区分缩小了凭据泄露的影响面：应用服务只应保存完成模型调用所需的 Key，而不应保存能够管理账户的凭据。 ### 配额与限制如何协作 用户账户可拥有总额度，API Key 还可以具有剩余额度、有效期、模型限制、IP 限制或通道限制。请求只有在这些条件均满足时才会进入路由阶段。 当需要为不同应用、团队或环境隔离成本时，应为每个用途签发独立 Key，并在 Key 级别设置最小权限和可追踪的名称。 - 不要在网页、客户端安装包或公开仓库中暴露完整 API Key。 - 创建 Key 后妥善保存首次显示的明文；后续列表通常只显示脱敏值。 - 定期轮换不再使用或疑似泄露的 Key，并查看使用日志确认影响范围。 ### 常见排查顺序 当调用被拒绝时，依次核对 Key 状态和过期时间、余额或剩余额度、模型限制、IP 限制、用户分组，以及目标模型是否存在可用通道。 ## 快速接入统一 API Canonical URL: /wiki/guides/get-started 通过确定基础地址、创建受限 API Key、选择已启用模型并发送最小请求，可以先验证应用与网关之间的基本连通性。 目标：用一个最小、可审计的请求验证当前部署的模型调用路径。模型名和基础地址必须以该部署实际展示或管理员提供的信息为准。 ### 准备信息 准备部署的公开基础地址、一个仅用于该应用的 API Key，以及已在当前部署启用的模型名称。不要使用示例域名或假定某个模型在所有部署中可用。 如果应用原本使用 OpenAI 风格客户端，先确认该客户端所调用的路径和流式行为是否属于当前部署支持的兼容范围。 ### 发送最小请求 以下示例展示常见的 Bearer 鉴权方式。将域名、Key 和模型名替换为当前部署中真实且被授权的值，再逐步加入流式、工具调用或媒体参数。 ### 从验证走向生产 将基础地址和 Key 放入服务端环境变量或受管理的密钥存储。为每个环境使用不同 Key，记录模型与超时策略，并针对失败响应、限额耗尽和上游不可用建立降级行为。 ## 使用图片生成 API Canonical URL: /wiki/guides/image-generation 图片生成使用统一的 OpenAI 风格路径；网关根据模型和通道将请求转换为相应上游格式，调用方仍应按模型能力传递参数。 范围：文生图使用 POST /v1/images/generations，图生图或编辑使用 POST /v1/images/edits。并非每个模型都支持相同的尺寸、质量、格式或编辑能力。 ### 选择操作与模型 先区分需要从文本创建图片，还是要基于已有图片编辑或再生成。然后从当前部署的模型目录中选择支持该操作的模型。模型名、可用尺寸与返回格式以具体通道能力为准。 ### 构造请求 通用请求至少包含 model 与 prompt。可按模型支持情况添加 n、size、quality、response_format、background 等字段。未在通用字段表中的扩展参数是否能透传，取决于通道配置。 ### 验证输出与成本 确认响应中的 URL 或 Base64 输出格式与应用预期一致，并在存储、展示或转存前评估链接的有效期与访问权限。生成次数、尺寸、质量和模型都可能影响成本，应以公开价格页和实际用量记录为准。 ## 使用 Seedance 视频生成 API Canonical URL: /wiki/guides/seedance-video 视频生成通过统一接口创建任务并查询结果；文本、图片、首尾帧和参考视频等输入类型会影响请求参数、模型选择与计费。 范围：创建任务使用 POST /v1/videos/generations，查询任务使用 GET /v1/videos/generations/{task_id}。兼容别名不改变需要 API Key 的事实。 ### 确定输入场景 纯提示词对应文生视频；首尾帧需要至少两张图片；参考图或参考视频则需要对应的公开可访问素材。input_type 可以显式指定，也可在部分场景由素材自动推断。 不要把分辨率、时长和音频支持视为所有模型的共同能力。应先核对所选模型的支持范围，再发送生产任务。 ### 创建并轮询任务 提交时包含 model、prompt，以及与场景匹配的 images、videos、audios、resolution、ratio 和 duration。响应中的任务标识用于后续查询；应用侧应使用退避轮询或回调机制，避免高频重复请求。 ### 处理异步结果 视频任务不是即时聊天响应。保存任务 ID、请求参数和调用方关联信息，查询完成状态后再消费最终资源。对于超时、失败或素材不可访问等情况，应向用户展示可操作的错误信息。 ## 公司简介 Canonical URL: /wiki/reference/company-profile 杭州飞鸾数字科技有限公司围绕 AI 服务开展业务，以国内与国外中转聚合站为主导业务线，并提供面向用户的 AI 应用。 主体：杭州飞鸾数字科技有限公司。负责人：冯飞。公司以 AI 模型聚合与中转服务为核心，同时建设国内、海外及 AI 应用三条业务线。 ### 公司信息 杭州飞鸾数字科技有限公司是一家面向 AI 服务与应用场景开展业务的数字科技公司。公司聚焦于为不同地区和不同使用场景提供稳定、清晰的 AI 服务入口。 - 公司名称：杭州飞鸾数字科技有限公司 - 负责人：冯飞 - 地址：浙江省杭州市余杭区仓前街道景兴路999号10幢304-31室 - 电话 1：057156033886 - 电话 2：17275438931 ### 三大主营业务线 公司目前运营三条面向不同市场和使用需求的业务线。其中，中转聚合站是公司的主导业务主线，重点服务于 AI 模型的统一接入、聚合与中转需求。 ### 业务重点 聚合站是公司当前的主导业务。通过统一服务入口和聚合能力，业务线服务于模型接入、调用管理与多场景应用需求。国内站与国外站分别面向对应市场，AI 应用业务线则进一步承接面向终端用户的应用场景。 各站点实际可用的模型、价格、功能与服务规则以相应站点公开页面和用户协议为准。 ## 认证方式参考 Canonical URL: /wiki/reference/api-authentication 本参考说明 API Key、Session Cookie 和 Access Token 的职责，以及何时必须携带 New-Api-User 请求头。 规则：AI 中继调用使用 API Key。用户钱包、Key 列表等 Dashboard 类接口使用 Session 或 Access Token；使用 Access Token 时通常还需提供匹配的 New-Api-User。 ### AI 中继接口 调用模型或媒体生成接口时，在 Authorization 头中使用 Bearer API Key。Key 的状态、配额、模型限制与 IP 限制会在请求执行前受到校验。 ### 用户与管理接口 查询用户资料、余额、Key 列表或修改账户配置时，使用浏览器 Session 或 Access Token，而不是 sk- API Key。跨域或服务端使用 Access Token 时，请求还应携带与该 Token 所属用户一致的 New-Api-User。 ### 安全要求 不要把 Session、Access Token 或 API Key 放进 URL 参数。仅在 HTTPS 连接中发送凭据，最小化每个凭据可访问的范围，并在泄露疑虑出现时立即轮换。 ## 通道权限参考 Canonical URL: /wiki/reference/channel-permissions 通道权限可以限制用户创建 API Key 时可选择的上游通道，并在运行时将路由候选集限定在允许的通道范围内。 规则：通道权限采用允许列表。它先过滤候选通道，再继续现有的健康、权重、重试和切换逻辑；管理员和超级管理员的可见范围遵循管理权限规则。 ### 用户权限与 Key 限制 管理员可为用户分配可选通道。普通用户创建 Key 时，选择的 channel_ids 必须属于自己的授权范围；管理员创建 Key 时仍会校验通道是否存在。 Key 级别的通道允许列表适合将一个应用或环境绑定到明确的上游范围，而不改变其他 Key 的路由策略。 ### 运行时行为 请求进入路由时，系统先按 Key 允许列表过滤候选通道，再应用既有的优先级、权重、健康与重试行为。权限不会改变某个通道对模型的支持范围，也不会强制选择不可用通道。 ### 配置建议 先为用户定义最小必要通道集合，再在每把 Key 上按应用用途进一步收窄。变更后使用该用户的测试 Key 验证模型请求与故障切换，避免仅以管理员视角判断。