API 开发文档

快速集成指南与完整 API 参考

快速开始

认证方式

核心概念

快速开始

注册并获取 Token

Token 以 sk- 开头，在控制台创建。

读取模型目录

先读取 /v1/models，获取当前真实可用模型。

按能力调用统一接口

文本、图片、视频、音频分别走不同 /v1 端点。

统一根地址

bash

https://api.uaiapi.com/v1

认证方式

所有公开模型接口都使用 Bearer Token 认证。

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token 以 sk- 开头，在控制台的 API Token 管理页面创建和管理。如果 Token 配置了模型权限，请求时只能调用被授权的模型。API Token 管理.

核心概念

概念	说明
Provider	模型的归属方，只负责品牌与元数据展示，不直接参与路由。
Model	平台对外暴露的标准模型主档。计费方式、价格、能力标签都挂在模型上。
Channel	具体的上游接入实例，维护协议、鉴权、优先级和可达性。
Binding	模型和渠道的显式绑定关系，决定模型是否可实际调用。

模型对外可用的条件是：模型本身启用，并且至少绑定了一个启用中的渠道。能力类型只用于筛选和演练场分类，不参与计费判断。

计费逻辑

billing_type	说明
token	输入 / 输出 Token 分开计费，适用于大部分文本与多模态模型。
request	按成功请求次数结算。
image_count	按最终返回图片张数结算。
duration_seconds	按视频时长（秒）结算。
token_total	按总 Token 结算，不区分输入输出。

图片模型可以按次或按张计费；视频模型可以按次、按秒或按总 Token 计费。当前计费方式完全由模型配置决定，不由能力类型自动推断。视频任务在创建时先预扣，进入终态后再做二次结算。

文本 / 多模态接口

POST/v1/chat/completions

文本和多模态统一走该接口。多模态模型仍通过 messages 传入内容，只是内容里可能带图片等多模态对象。

curl

bash

curl https://api.uaiapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": false
  }'

图片生成

POST/v1/images/generations

统一图片生成接口，支持 prompt、n、size、quality、image_url 等字段。按张计费模型会根据最终返回张数结算。

curl

bash

curl https://api.uaiapi.com/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A clean editorial product poster",
    "n": 2,
    "size": "1024*1024"
  }'

视频生成

POST/v1/videos/generations

创建任务

GET/v1/videos/generations

查询任务列表

GET/v1/videos/generations/:task_id

查询任务详情

DELETE/v1/videos/generations/:task_id

取消任务

视频任务是异步流程。创建任务后，后续查询、列表和取消都会回到原始渠道。任务在终态时会完成最终结算：成功按最终结果修正，失败或取消则退款。

创建任务

bash

curl https://api.uaiapi.com/v1/videos/generations \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "A slow cinematic pan through a rainy neon alley",
    "duration": 5,
    "ratio": "16:9"
  }'

工具接入

UAIAPI 提供 OpenAI 兼容接口，因此大多数支持 OpenAI Base URL 与 API Key 的工具都可以直接接入。

通用接入方式

对于支持 OpenAI 协议的客户端或开发工具，通常只需要替换 Base URL 为当前平台的 /v1 地址，并填入控制台创建的 API Key。

统一根地址

bash

https://api.uaiapi.com/v1

使用平台提供的安装脚本、本地引导命令或手动配置文件，都可以把 OpenClaw 接到 UAIAPI。点击后可直接跳到下方配置章节。

OpenCode

如果 OpenCode 当前版本支持自定义 OpenAI 兼容 Provider，可直接把 UAIAPI 作为外部模型服务接入。

打开 OpenCode 的 Provider / Model 配置页面。
选择自定义 Provider，或选择 OpenAI Compatible 类型。
将 Base URL 设置为 UAIAPI 的 /v1 地址，并填入控制台生成的 API Key。
选择你在 UAIAPI 中实际可用的模型 ID 作为默认模型。

配置项	推荐值
Base URL	https://api.uaiapi.com/v1
API Key	sk-your-api-key
Model	YOUR_MODEL_ID

如果你的 OpenCode 版本没有自定义 OpenAI Provider 入口，则需要等待其官方支持，或通过中间代理方式接入。

OpenClaw

通过平台提供的安装脚本或本地引导命令，把 OpenClaw 接入到当前平台的 OpenAI 兼容接口。

1. 使用安装脚本自动配置

脚本会自动备份现有配置，并写入 Base URL、API Key、默认模型与别名。未提前传入 API Key 时，脚本会在终端中提示输入。

脚本地址

text

https://www.wei.run/setup-openclaw-provider.sh
https://www.wei.run/setup-openclaw-provider.ps1

安装脚本命令

bash

curl -fsSL https://www.wei.run/setup-openclaw-provider.sh | bash

# Optional: provide key non-interactively
curl -fsSL https://www.wei.run/setup-openclaw-provider.sh | WEIAPI_API_KEY=sk-your-api-key bash

Windows 执行示例

powershell

iwr https://www.wei.run/setup-openclaw-provider.ps1 -OutFile .\setup-openclaw-provider.ps1
powershell -ExecutionPolicy Bypass -File .\setup-openclaw-provider.ps1

# Optional: provide key non-interactively
powershell -ExecutionPolicy Bypass -File .\setup-openclaw-provider.ps1 -ApiKey "sk-your-api-key"

2. 使用本地引导向导

如果你更偏好交互式流程，可运行 openclaw 自带引导：Yes -> QuickStart -> Custom Provider，然后依次填写 Base URL、API Key 与默认模型。

OpenClaw 引导命令

bash

openclaw onboard

引导向导建议填写

Base URL: https://api.uaiapi.com/v1
API Key 填写控制台创建的 sk- 开头密钥。
Provider Type 选择 Custom Provider / OpenAI-compatible。
Model ID 直接填写 UAIAPI 中实际可用的模型 ID，例如 qwen3.5-plus。
保存后如需设为默认主模型，可将该 provider 设为 primary。

3. 手动编辑配置文件

若不使用脚本或向导，可直接编辑 openclaw.json 并按下方示例填写。

推荐配置示例

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom-api-wei-run/qwen3.5-plus"
      },
      "models": {
        "custom-api-wei-run/qwen3.5-plus": {
          "alias": "qwen3.5-plus"
        }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "custom-api-wei-run": {
        "baseUrl": "https://api.uaiapi.com/v1",
        "api": "openai-completions",
        "apiKey": "sk-your-api-key",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus (Custom Provider)",
            "contextWindow": 1000000,
            "maxTokens": 32768,
            "input": ["text", "image"],
            "reasoning": false,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      }
    }
  }
}

默认配置文件路径

macOS / Linux: ~/.openclaw/openclaw.json

Windows: $HOME\.openclaw\openclaw.json

配置键	说明
models.providers.*.baseUrl	上游 API 根地址，建议填写本平台 /v1 根路径。
models.providers.*.api	协议类型。对大多数模型使用 openai-completions。
models.providers.*.apiKey	在控制台创建的 API Key（sk- 开头）。
models.providers.*.models[].id	直接填写 UAIAPI 中实际可用的模型 ID，例如 qwen3.5-plus。
models.providers.*.models[].input	模型输入类型数组；如需图像输入，必须包含 image。
agents.defaults.model.primary	默认主模型路由入口，可映射到你最常用的模型。

配置更新后（可选）重启

bash

openclaw gateway restart

错误排查

HTTP	错误类型	说明
400	invalid_request_error	请求参数错误或缺少必填字段。
401	authentication_error	Token 无效、缺失或过期。
402	insufficient_quota	余额不足，或可赠送次数已耗尽且无法继续扣费。
404	model_not_found	模型不存在，或当前没有可用绑定渠道。
429	rate_limit_error	请求频率超限。
502	upstream_error	上游渠道执行失败。
500	server_error	平台内部错误，可结合 request_id 追踪。