02 / 接口

一个下午就能接进你的应用。

同一套状态机，通过 JSON 调用。你的应用用我们发放的密钥访问它——可以来自 Swift、Kotlin、Python、浏览器或 Node 后端——并保留自己的符号、声音与界面。

路径一 · 嵌入

Node、Electron 或后端。

引入工厂函数，渲染完全由你掌控。运行时不会替你获取或绘制任何素材。

import { createTinkySpeak } from 'tinkyspeak-runtime';

const session = createTinkySpeak({
  provider: { kind: 'tinkymind' },
  language: 'en', partnerLanguage: 'en',
  profile: { age: 7, level: 'sentence', choices: 6 },
  symbols: choice => yourArtworkFor(choice),
});
const state = await session.hear({ text: 'Would you like a drink?' });
renderYourTiles(state.choices);

// In YOUR user-selection handler:
const selected = session.select({ choiceId: chosenTileId });
const pending  = await session.speak({ draftId: selected.draft.id });
// Your app delivers pending.speech.text in pending.speech.language.
session.confirmSpeech({ speechId: pending.speech.id, outcome: 'spoken' });

路径二 · HTTP

任意语言，任意平台。

运行 tinkyspeak serve，整个引擎就是 127.0.0.1:7437 上的本地 JSON 接口。随包提供的 fetch 客户端不含任何 Node 引用，可直接打包进网页应用。

import { createTinkySpeakClient } from 'tinkyspeak-runtime/client';

const api     = createTinkySpeakClient({ url: 'http://127.0.0.1:7437' });
const session = await api.createSession({ language: 'en', partnerLanguage: 'en' });
const state   = await session.hear({ text: 'Are you hungry?' });
renderYourTiles(state.choices);

const selected = await session.select({ choiceId: chosenTileId });
const pending  = await session.speak({ draftId: selected.draft.id });
await yourSpeechEngine(pending.speech.text, pending.speech.language);
await session.confirmSpeech({ speechId: pending.speech.id, outcome: 'spoken' });

路由	说明
`GET /v1/capabilities`	模型语言元数据、会话记忆上限与输出归属。
`POST /v1/sessions`	可选 language、partnerLanguage、profile、context；返回带 id 的状态。
`POST /v1/sessions/ID/hear`	对方说的话；返回包含选项的状态。
`POST /v1/sessions/ID/select`	选中的 choiceId，可附修改后的文本；生成草稿。
`POST /v1/sessions/ID/compose`	使用者自己的话；生成草稿。
`POST /v1/sessions/ID/speak`	draftId；在 `speech` 中返回交由应用执行的送出请求。
`POST /v1/sessions/ID/confirm-speech`	spoken、displayed、failed 或 cancelled。
`POST /v1/sessions/ID/scan`	Base64 图像与模式；返回观察结果与可选磁贴。
`POST /v1/sessions/ID/languages`	对方与使用者的语言，按模型校验。
`DELETE /v1/sessions/ID`	关闭会话并取消其工作。

选择、草稿与送出 ID 可防止过期或重复操作。并发操作返回 409 session_busy。错误以 {"error":{"code":"...","message":"..."}} 形式返回。运行时不记录任何对话请求体。

仍由你的应用负责的部分

这条边界是刻意划定的。

送出

运行时返回确切文本、语言与一个送出 ID。由你的应用朗读或显示，再回报结果。HTTP 服务本身从不发声。

素材

每个选项都带有句子、标签、表情与 ID。可通过 symbols(choice) 提供自己的符号或照片，也可在配置中按确切句子映射。表情始终是兜底。

身份与权限

这是单一可信应用的接口。面向多用户时，账号、授权与会话归属由你的后端负责。

模型适配

沿用你已经在用的模型。

运行时提供适配器，不附带权重。

{ kind: 'tinkymind' }                       // 已安装的本地儿童模型；仅英语
{ kind: 'gemini',   model: 'YOUR_MODEL', apiKeyEnv: 'GEMINI_API_KEY' }
{ kind: 'ollama',   model: 'YOUR_INSTALLED_MODEL' }
{ kind: 'compatible', endpoint: 'https://your-model.example/v1', model: 'YOUR_MODEL' }
{ kind: 'board',    tiles: yourAuthoredTiles }  // 完全不使用生成式模型

继续阅读试一试