潮汐语音合成

本来只打算花十分钟看看，结果因为下面这个问题多折腾了半小时。

文档里 `POST /v1/batch` 的示例请求用 `items`，SDK 类型定义里却是 `requests`，两边对不上，我按示例写直接被类型检查拦住，只能翻源码才知道该用哪个。

在 429 响应头里明确 `Retry-After` 的单位并给出示例；希望客户端退避逻辑一次写对，减少无效重试和重复请求。

分页游标在特定 limit 下直接消失，看起来像翻到底了，其实数据已经丢了。

本来只打算花十分钟看看，结果因为下面这个问题多折腾了半小时。

`POST /v1/chat` 的 `max_tokens` 传 4096 返回 400 `max_tokens exceeds model limit`，可文档的模型表写这个模型支持 8192 输出，而 2048 又能过，真实上限像是 3000 左右，全靠试。

给 Python SDK 提供真正的异步客户端，或把文档示例从 `async def` 里挪出来；改完 FastAPI 在压测时就不会堵事件循环。

免费额度和速率限制挤在同一组响应头里，容量估算经常差一个数量级。

我是拿它来处理上周积压的事情的，数据量比平时大一些，正好压一压。

初始化 SDK 用 `new Client({ apiKey })`，key 从环境变量读，本地正常；部署到 Vercel 后所有请求都 401，排查两小时才发现 SDK 在模块加载时就把 key 快照了，运行时注入的变量根本没读到。

给 Python SDK 提供真正的异步客户端，或把文档示例从 `async def` 里挪出来；改完 FastAPI 在压测时就不会堵事件循环。

免费额度和速率限制挤在同一组响应头里，容量估算经常差一个数量级。

我当时的调用大概是这样：

// 脱敏示例：超时与重试语义无法区分
func chatWithTimeout(ctx context.Context, c *beehub.Client, prompt string) (*beehub.ChatResponse, error) {
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()
    res, err := c.Chat(ctx, beehub.ChatRequest{
        Model:    "bh-small",
        Messages: []beehub.Message{{Role: "user", Content: prompt}},
    })
    if errors.Is(err, context.DeadlineExceeded) {
        // 首次超时和重试预算耗尽都长这样
        return nil, fmt.Errorf("chat timeout: %w", err)
    }
    return res, err
}

第一次打开是抱着试试看的心态，结果在第一步就卡了一会儿，后面才顺起来。

`GET /v1/models` 返回的 `context_window` 在 gpt 系列上恒为 0，其它模型正常，我在代码里用它做上下文截断判断，结果所有 gpt 请求都被截成空字符串。

SDK 改成运行时读取 key，或在文档里给出 `Client.fromEnv()` 的 Serverless 用法；希望 key 不用写进构建产物也能生效。

返回值把无数据和 0 混为一谈，客户端分不清，业务代码里到处是特判。