Alphawrite SDK API 文档

版本 1.0.0 · 2026-09-23 · 零依赖 JS/TypeScript SDK，覆盖微信小程序、浏览器与 Node 18+

接口概览

可用模型

价格单位：元 / 百万 Token。实际可用模型以 models() 返回为准。

安装

npm install https://sdk.alphawrite.cn/download/alphawrite-sdk-1.0.0.tgz

也可以用单文件版，适合浏览器 <script> 或微信小程序：

<script src="https://sdk.alphawrite.cn/v1/alphawrite-sdk-1.0.0.global.js"></script>
<script>
  const { Alphawrite } = window.AlphawriteSDK
</script>

初始化

import { Alphawrite } from 'alphawrite-sdk'

const client = new Alphawrite({
  apiKey: process.env.ALPHAWRITE_KEY,
  baseURL: 'https://model.alphawrite.cn/v1',
  timeout: 120000,
  mode: 'server'
})

AlphawriteOptions

models()

列出当前 Key 可用的模型。

const models = await client.models()
// [{ id: 'qwen3.8-flash', object: 'model', ownedBy: 'ali' }, ...]

chat(options)

OpenAI 风格对话接口，对应 POST /v1/chat/completions。

const r = await client.chat({
  model: 'qwen3.8-flash',
  messages: [
    { role: 'system', content: '你是一个税务助手' },
    { role: 'user', content: '帮我看看这家企业的风险点' }
  ],
  maxTokens: 512,
  temperature: 0.7
})
console.log(r.content, r.usage)

ChatOptions

ChatResult

responses(options)

OpenAI Responses 接口，对应 POST /v1/responses。

const r = await client.responses({ model: 'qwen3.8-flash', input: '总结这段文字' })
console.log(r.content, r.status)

messages(options)

Anthropic Messages 格式，对应 POST /v1/messages，供 Claude Code 这类客户端使用。

const r = await client.messages({
  model: 'qwen3.8-flash',
  system: '你是一个税务助手',
  messages: [{ role: 'user', content: '回答两个字：好的' }],
  maxTokens: 256
})
console.log(r.content)

流式输出

四个方法都支持流式。SDK 内部按 \n\n 切分 SSE 事件，并处理跨分片的 UTF-8 半字符，接入方不需要自己解析。

let text = ''
const r = await client.chat({
  model: 'qwen3.8-flash',
  messages: [{ role: 'user', content: '从 1 数到 5' }],
  maxTokens: 256,
  stream: true,
  onDelta: (chunk) => { text += chunk },   // 正文
  onReasoning: (chunk) => {}              // 思维链，可选
})

// 保证一致：拼接结果 === 返回的 content
console.log(text === r.content) // true

微信小程序

小程序没有 EventSource，SDK 自动切换到 wx.request + enableChunked。使用方式完全一致，不需要改代码。

错误处理

所有错误都是 AlphawriteError。

import { AlphawriteError } from 'alphawrite-sdk'

try {
  await client.chat({ model: 'qwen3.8-flash', messages: [{ role: 'user', content: 'hi' }] })
} catch (e) {
  if (e instanceof AlphawriteError && e.isAuthError) {
    // Key 无效或无权访问该分组
  }
}

运行环境

环境自动检测：存在 wx.request 时走小程序适配器，否则走 fetch。也可以用 fetch 参数自定义。

安全建议

小程序 / 浏览器
      ↓ 短期 Token（你们的后端签发，可限额度、限模型、可撤销）
你们的业务后端
      ↓ 长期 API Key（存在服务端环境变量）
model.alphawrite.cn/v1

SDK 用 mode 区分两种场景：server（默认）不做提醒；client 会在初始化时提示不要在前端使用长期密钥。

已知限制

• qwen3-vl-plus 不支持 /v1/responses，请用 chat()。
• 图片输入要求边长大于 10 像素，否则上游返回 InvalidParameter。
• Anthropic 格式的 maxTokens 建议 200 以上，否则可能被思维链占满。
• 模型定价与可用模型以 models() 返回和实际账单为准。