使用概述

词元井(TokenWell)开放平台提供标准的 HTTP API 接口，支持多种编程语言和开发环境。API 兼容 OpenAI SDK，将 base_url 指向词元井即可无缝迁移现有应用。

API 端点

本平台的通用 API 端点如下：

所有 API 请求均需使用 HTTPS 协议。基于资源的 URL 路径会附加在上述 Base URL 之后，例如 /chat/completions。

身份验证

词元井 API 使用 Bearer Token 认证。在请求 Header 中附加 Authorization 字段，值为 Bearer YOUR_API_KEY。

curl https://www.tokenwell.com.cn/v1/models \
  -H "Authorization: Bearer $TOKENWELL_API_KEY"

首次调用

以下示例演示了如何用 doubao-seed-2-0-lite-260215 生成一段对话回复。所有代码均已验证可直接运行，请将 YOUR_API_KEY 替换为你的真实密钥。

curl -X POST "https://www.tokenwell.com.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seed-2-0-lite-260215",
    "messages": [
      {"role": "system", "content": "你是一个专业的AI助手。"},
      {"role": "user", "content": "你好，请介绍一下自己。"}
    ],
    "temperature": 1.0,
    "stream": false
  }'

响应格式

所有 Chat Completions 接口返回的 JSON 结构遵循 OpenAI 规范，便于现有生态工具开箱即用：

{
  "id": "chatcmpl-7xN3f2k...",
  "object": "chat.completion",
  "created": 1708502400,
  "model": "doubao-seed-2-0-lite-260215",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是词元井平台接入的 AI 助手..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 142,
    "total_tokens": 170
  }
}

错误处理

当请求失败时，API 会返回非 2xx 的 HTTP 状态码以及 JSON 错误体，包含 code 与 message 字段。详见 《错误码》章节。

• 401 Unauthorized — API Key 未提供或无效
• 429 Too Many Requests — 触发速率限制，建议实现指数退避重试
• 500 Internal Server Error — 平台内部错误，可带上 request-id 联系支持