五次调用，这就是一整场对话。

开启一个会话。

每场对话一个会话。它承载语言、阅读水平与记忆；只要还在交谈，就保留它的 id。

# $TINKYSPEAK_API_URL is the endpoint we issue with your key.
curl $TINKYSPEAK_API_URL/v1/sessions \
  -H "Authorization: Bearer $TINKYSPEAK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language":"en","partnerLanguage":"en","profile":{"level":"sentence","choices":6}}'

{ "id": "sess_8f2c…", "choices": [], "history": [] }

发送对方说的话。

这是你唯一必须发送的内容。你不需要发送使用者自己的话、历史或符号——线索我们已经持有。

curl $TINKYSPEAK_API_URL/v1/sessions/sess_8f2c…/hear \
  -H "Authorization: Bearer $TINKYSPEAK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Would you like tea or coffee?"}'

返回的内容可以直接绘制。每个选项都是完整句子，附磁贴用的短标签、作为兜底的表情符号，以及用于选择的 id：

{ "choices": [
    { "id": "ch_1", "label": "Tea",    "sentence": "I'd like tea, please.",    "emoji": "🍵" },
    { "id": "ch_2", "label": "Coffee", "sentence": "I'd like coffee, please.", "emoji": "☕" },
    { "id": "ch_3", "label": "Water",  "sentence": "Water, please.",           "emoji": "💧" }
  ] }

随你怎么画。

这是你的应用。三列、九列、照片、你自己的符号集、开关扫描、眼动——都与我们无关。我们绝不获取或绘制任何素材。用 choice.id 告诉我们选了哪一个。

送出，然后回报已发生。

我们给你确切的文字与语言。你的语音引擎把它说出来、你的屏幕显示它、你的设备做它该做的事——然后回报结果，因为只有已送出的话才会进入记忆。

// the person taps a tile in YOUR interface
POST /v1/sessions/ID/select        {"choiceId":"ch_1"}   → a draft
POST /v1/sessions/ID/speak         {"draftId":"…"}      → the exact words + language

// YOUR voice engine says them, then you report what happened
POST /v1/sessions/ID/confirm-speech {"speechId":"…","outcome":"spoken"}

继续。

把对方的下一句发过来，对话就会从真正说出口的话继续。此外无需管理任何东西——不用拼装提示词，也不用来回传送历史。

无需上传。指向你已有的资源即可。

这里没有符号上传功能，而且这是刻意的：你的素材留在你自己的服务器或应用包里，那里本就有你的版本管理与授权。你什么都不必交给我们——只需在渲染时把选项映射到你自己的符号库。

// Your library, your rules. Called for every choice before you draw it.
function artworkFor(choice) {
  const hit = myLibrary.find(choice.label, choice.sentence);
  return hit ? { kind: 'symbol', library: 'my-set', id: hit.id, alt: hit.alt }
             : null;            // null → the emoji stays as a fallback
}

选项携带的是词语与身份；它长什么样由你决定。你的符号集未覆盖的内容返回 null，表情符号就会保留，因此库里的空缺绝不会变成一块空白磁贴。更换素材绝不会改变被说出的词语。

完整接口。

错误以 {"error":{"code","message"}} 返回。选择、草稿与送出 id 均为一次性，因此过期的点击不会送出错误的句子。两个操作同时进行会返回 409 session_busy。