API 概览与基础地址

先理解这项功能

天工智算云通过当前站点的 /v1 路径提供 OpenAI 兼容模型接口。客户端需要发送 HTTPS 请求、Bearer API Key 和 JSON 或对应媒体数据；模型、价格、配额与支持能力以模型广场和控制台为准。GPU 实例控制面目前不在本参考中虚构为公开 OpenAPI。

本文面向通过天工智算云 OpenAI 兼容接口接入模型能力的后端开发者、架构师和运维人员。完成本文后，你应当能够独立完成配置、验证结果，并知道出现异常时应该保留哪些信息。

云资源和模型能力会随区域、库存、模型版本及账号权限变化。页面显示的可用规格、价格、配额和状态是本次操作的直接依据；文档用于解释操作逻辑和风险边界。

完成后你将获得

• 能够构造、发送并验证接口请求
• 能够按状态码和 Request ID 定位失败
• 能够把密钥、用量、重试和内容安全纳入生产设计

应用通过认证调用 `/v1`，平台记录状态、用量与 Request ID。

开始前的准备

先完成以下准备，再进入控制台操作。对生产环境而言，准备阶段还应明确资源负责人、费用归属、数据级别和回滚方式。

• 从控制台创建仅供当前后端环境使用的 API Key，并安全保存完整值
• 在模型广场确认模型名称、能力、价格和当前可用状态
• 准备不含无必要个人信息、商业秘密或未授权素材的测试输入
• 为 HTTP 客户端配置连接超时、响应超时、并发上限和可观测日志

完整操作步骤

按照下面的顺序执行。每完成一步都应检查页面反馈，不要在状态仍为“处理中”时连续提交相同操作。涉及删除、重装、退款、密钥禁用等不可逆动作时，应再次核对资源名称和影响范围。

1. 确定基础地址

使用平台正式站点公布的基础地址，并在其后拼接 /v1。不同环境应通过配置管理基础地址，不在业务代码散落常量。

2. 选择端点

文本使用 /v1/chat/completions，模型发现使用 /v1/models，其他模态按本栏目对应接口。先确认模型支持目标端点。

3. 添加认证头

发送 Authorization: Bearer <API_KEY>。JSON 请求同时设置 Content-Type: application/json。

4. 发送最小请求

先用短输入、非流式和默认参数验证连通性，再逐步启用流式、多模态或高并发。

5. 解析响应

同时处理 HTTP 状态、错误对象、业务结果、结束原因、用量和 Request ID。不要只判断响应体是否包含文本。

6. 建立生产基线

配置超时、并发、限流、重试、日志脱敏、预算和降级策略后再接入真实流量。

生产使用建议

功能能够使用并不等于已经具备生产条件。正式承载业务前，请把可观测性、权限、费用和数据恢复纳入同一套运行基线。

• 通过服务端密钥管理系统注入 API Key，不写入网页、移动端、源码、镜像或日志
• 记录模型、耗时、状态、用量和 Request ID；输入输出日志按业务需要脱敏
• 对限流和临时服务错误使用指数退避、随机抖动和总重试上限
• 对模型输出做长度、类型、结构和安全校验，高风险结论由专业人员复核
• 在上线前完成容量、成本、故障注入和备选模型演练

建议为关键资源建立变更记录，至少包含操作者、时间、原因、预期结果、实际结果和回退步骤。团队协作时，不要通过聊天工具传递密码或完整 API Key。

相关规则

• 大模型云服务协议
• 创建与管理 API Key

常见问题与排查

排查时先确认影响对象、开始时间和最近一次变更，再区分是浏览器、账号权限、平台资源、网络还是应用自身问题。提交工单时，请附上资源 ID、请求 ID、发生时间、错误信息和已经执行过的排查步骤；不要提交密码、完整密钥或身份证件原图。

返回 401 或 403

检查 Bearer 认证格式、密钥状态、所属环境与模型权限。不要在排障信息中提供完整密钥。

返回 400 或参数错误

使用最小请求逐项检查模型名称、字段类型、消息结构、文件格式和上下文长度，不要盲目重试相同请求。

返回 429、5xx 或网络超时

限制并发并受控退避。记录 Request ID；若流式响应已经产生部分内容，先判断业务写入是否可安全重放。

完成检查清单

离开页面前，逐项确认：

• 操作对象、所属项目和费用主体正确，页面状态与预期一致
• 关键数据已有独立副本，临时文件、公开端口和测试密钥已经清理
• 资源负责人、预算与通知接收人已经明确
• 必要的资源 ID、订单号或 Request ID 已记录，便于后续审计和支持
• 已阅读与本功能相关的专项协议，并理解计费、数据和违规处置规则

如结果与本文不一致，应停止继续扩大变更范围，通过页面右上角“工单支持”提交问题。