文档预览

为企业集成准备的统一接口。

以下内容用于说明预期接入方式；真实接口契约确认后才会开放可复制示例。

接口示意，尚未开放

01契约概念

基础 URL 与认证概念

基础地址仅表示未来 Gateway 的独立边界；在对外开放前，不接受任何请求。

基础 URL: https://api.valencegrid.com
Authorization: 企业密钥将通过 Authorization 请求头传递；官网不会创建、存储或读取密钥。

Gateway 接口契约确认前，本页的路径、字段与示例均为说明性内容，不代表可运行接口。

02数据结构

请求与统一响应示意

字段名、嵌套关系和值均为说明框架，不构成已确认的 API 契约。

请求结构

{
  "model": "illustrative-model-id",
  "input": [
    {
      "role": "user",
      "content": "Illustrative enterprise request."
    }
  ]
}

统一响应结构

{
  "id": "illustrative-request-id",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "content": "Illustrative response."
    }
  ],
  "usage": {
    "input_units": 0,
    "output_units": 0
  }
}

03示例框架

三种未开放的集成外形

以下片段只展示未来文档可能采用的表达方式；均缺少有效路径、字段契约和凭据，不可复制运行。

cURL

不可运行示意

curl --request POST "https://api.valencegrid.com/<illustrative-path>" \
  --header "Authorization: Bearer <enterprise-key>" \
  --header "Content-Type: application/json" \
  --data '<illustrative-request-body>'

Python

不可运行示意

# 仅表示未来 SDK 的数据外形，不发起网络请求
request_spec = {
    "model": "illustrative-model-id",
    "input": "<illustrative-input>",
}

JavaScript

尚未开放，不可运行

// 仅表示未来 SDK 的数据外形，不包含浏览器 API 调用
const requestSpec = Object.freeze({
  model: "illustrative-model-id",
  input: "<illustrative-input>",
});

04错误处理

错误分类

接入开放后，请以正式接口契约和服务端返回信息为准。

类别	含义	处理原则
认证失败	密钥无效或权限不足	停止重试并检查企业权限
请求受限	达到调用或用量限制	根据服务端提示退避重试
上游暂不可用	目标模型短时不可用	按企业路由策略处理
请求无效	参数或模型标识不符合契约	修正请求后再提交

05重试原则

重试原则

把短时波动与不可恢复的请求问题分开处理。

对可恢复错误使用有上限的指数退避，避免持续放大负载。
为每次请求保留请求标识，便于企业侧追踪、关联和排障。
认证失败或请求无效时不进行盲目重试，应先检查权限或修正请求。

完整文档将在 docs.valencegrid.com 部署后迁移至该站点。