Skip to content

api_setup.md

Latest commit

 

History

History
301 lines (206 loc) · 6.75 KB

api_setup.md

File metadata and controls

301 lines (206 loc) · 6.75 KB
Raw

ThinkAI API Key 获取与环境配置

1. 申请 ThinkAI Token

步骤一：注册账号

访问 顶想云控制台 注册账号并登录。

步骤二：生成 Token

  1. 进入 Token 管理页面
  2. 点击「生成新令牌」
  3. 重要：在权限设置中勾选「启智AI」，否则无法调用 ThinkAI 接口
  4. 设置令牌名称（如：tai-cli）
  5. 设置过期时间（可选）
  6. 复制生成的 Token（只显示一次，请妥善保存）

步骤三：账户充值

ThinkAI 是付费服务，需要在控制台充值后才能调用：

  • 进入 充值页面
  • 选择充值金额（建议先充值少量测试）
  • 支付方式：支付宝、微信等

步骤四：查看配额

  • 在控制台查看 使用情况
  • 了解各模型的调用价格

2. 环境变量配置

tai CLI 支持通过环境变量配置认证信息。

必需的环境变量

变量名 必填 说明 示例
THINKAI_API_KEY 是 ThinkAI 的 API Token tk-xxxxxxxxxxxxxxxx
THINKAI_BASE_URL 否 API 服务地址（一般无需修改） https://api.topthink.com

配置方式

临时设置（当前会话有效）

# Linux / macOS
export THINKAI_API_KEY="tk-xxxxxxxxxxxxxxxx"
export THINKAI_BASE_URL="https://api.topthink.com"

# Windows CMD
set THINKAI_API_KEY=tk-xxxxxxxxxxxxxxxx
set THINKAI_BASE_URL=https://api.topthink.com

# Windows PowerShell
$env:THINKAI_API_KEY="tk-xxxxxxxxxxxxxxxx"
$env:THINKAI_BASE_URL="https://api.topthink.com"

永久设置（推荐）

Linux / macOS：编辑 ~/.bashrc 或 ~/.zshrc

# 追加到配置文件
echo 'export THINKAI_API_KEY="tk-xxxxxxxxxxxxxxxx"' >> ~/.bashrc
echo 'export THINKAI_BASE_URL="https://api.topthink.com"' >> ~/.bashrc

# 立即生效
source ~/.bashrc

Windows：

  1. 右键「此电脑」→ 属性 → 高级系统设置 → 环境变量
  2. 在「系统变量」中新建：
    • 变量名：THINKAI_API_KEY，值：tk-xxxxxxxxxxxxxxxx
    • 变量名：THINKAI_BASE_URL，值：https://api.topthink.com
  3. 重启终端生效

使用 .env 文件（项目级别）

在项目根目录创建 .env 文件：

THINKAI_API_KEY=tk-xxxxxxxxxxxxxxxx
THINKAI_BASE_URL=https://api.topthink.com

加载方式：

# 使用 direnv 工具
# Ubuntu: apt install direnv
# macOS: brew install direnv

# .envrc 文件
source .env

# 或者手动加载
export $(cat .env | xargs)

3. 验证配置

检查 tai CLI 是否安装

tai --version

验证 Token 是否有效

# 发起一次简单调用测试
tai chat --model gpt-3.5-turbo --message "你好"

成功返回结果说明配置正确。如果失败，请检查：

错误信息 原因 解决方案
Unauthorized Token 错误或过期 重新生成 Token
Permission denied Token 未勾选启智AI 在控制台勾选权限
Insufficient balance 账户余额不足 充值
Connection refused BASE_URL 错误 检查网络和 URL

查看当前配置

# 查看 tai CLI 配置
tai config list

# 显示当前环境变量
echo $THINKAI_API_KEY

🌟 首次使用建议：获取支持的模型列表

强烈建议首次使用前先查看模型列表，了解可用的模型 code，避免使用过时或错误的模型名。

# 列出所有支持的模型
tai model list

# 按类型筛选
tai model list --type chat      # 对话模型
tai model list --type image     # 图片模型
tai model list --type audio     # 语音模型
tai model list --type video     # 视频模型
tai model list --type music     # 音乐模型

# 查看特定模型详情（必须指定 type 和 code）
tai model show image gpt-image-2
tai model show chat gpt-4
tai model show music volcengine

完整模型列表和选择指南请参考 references/models.md。

4. 多环境管理

场景：开发/生产环境使用不同 Token

# .env.development
THINKAI_API_KEY=tk-dev-xxxxx
THINKAI_BASE_URL=https://api.topthink.com

# .env.production
THINKAI_API_KEY=tk-prod-xxxxx
THINKAI_BASE_URL=https://api.topthink.com

场景：多用户协作

每个用户设置自己的 THINKAI_API_KEY：

# 用户 A
export THINKAI_API_KEY="tk-user-a-xxxxx"

# 用户 B
export THINKAI_API_KEY="tk-user-b-xxxxx"

5. 安全建议

⚠️ 请务必保护好你的 API Key！

DO ✅

  • 将 Token 保存在环境变量或密钥管理工具中
  • 为不同项目使用不同的 Token
  • 定期轮换 Token
  • 设置合理的过期时间
  • 在 .gitignore 中忽略 .env 文件

DON'T ❌

  • ❌ 不要将 Token 提交到 Git 仓库
  • ❌ 不要在公开场合分享 Token
  • ❌ 不要在客户端代码中硬编码 Token
  • ❌ 不要使用长期不过期的 Token

.gitignore 推荐配置

# 环境变量文件
.env
.env.local
.env.*.local

# tai 配置
.tai/

6. 常见问题

Q: Token 泄露了怎么办？

立即在控制台「撤销」该 Token，并生成新 Token。

Q: 如何查看 Token 使用情况？

在控制台的 使用记录 页面查看详细的调用记录和费用。

Q: 能否多人共享一个 Token？

可以，但不推荐。建议为每个成员生成独立 Token，便于：

  • 单独统计使用量
  • 单独计费
  • 出现问题时单独撤销

Q: 环境变量不生效？

# 1. 检查变量是否设置
echo $THINKAI_API_KEY

# 2. 如果为空，确认设置方式是否正确

# 3. 重启终端或重新加载配置
source ~/.bashrc

# 4. 检查是否有同名变量覆盖
env | grep THINKAI

Q: 能否使用其他厂商的 API Key？

可以。tai CLI 支持自定义 BASE_URL，可以对接兼容 OpenAI 协议的服务：

# 智谱 AI
export THINKAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4"
export THINKAI_API_KEY="your_zhipu_key"

# 通义千问
export THINKAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export THINKAI_API_KEY="your_dashscope_key"

# 自部署服务
export THINKAI_BASE_URL="http://localhost:8000/v1"
export THINKAI_API_KEY="any-string"

7. 完整配置示例

一次性配置（推荐首次使用）

# 1. 设置环境变量
cat >> ~/.bashrc << 'EOF'

# ThinkAI 配置
export THINKAI_API_KEY="tk-xxxxxxxxxxxxxxxx"
export THINKAI_BASE_URL="https://api.topthink.com"
EOF

# 2. 立即生效
source ~/.bashrc

# 3. 验证
tai --version
tai chat --model gpt-3.5-turbo --message "测试"

完成以上步骤后，tai CLI 就可以正常调用所有 ThinkAI 能力了。