Harness API

Harness 是 AI降临派面向硬件和应用的角色对话服务：你通过 HTTP 接口创建带人设、记忆、技能和工具的「角色」，设备再用一条 TCP 长连接和角色实时语音对话。如果你只需要一个裸的语音模型（自己管理提示词和上下文），请看 Realtime API。两套接口共用控制台的账号和 key。

Harness is Adventists AI's character conversation service for devices and apps. You create characters (persona, memory, skills, tools) over HTTP, and the device talks to a character in real time over one long-lived TCP connection. If you just need a bare voice model and manage prompts yourself, see the Realtime API. Both share the same console account and keys.

概览Overview

两个入口连的是同一套服务：账号、key、角色和记忆都是通用的。海外入口经新加坡专线加速。下文的路径都相对于 HTTP 入口，例如 POST /v2/init 指 https://api.adventists.cn/v2/init。8010 端口是测试端口，可能先于 8009 上线新功能，不保证稳定。

Both entry points reach the same service; accounts, keys, characters and memory are shared. The global entry is accelerated over our Singapore private line. Paths below are relative to the HTTP base, e.g. POST /v2/init means https://api.adventists.ai/v2/init. Port 8010 is a test port that may get features before 8009 and is not guaranteed to be stable.

WebSocket 和 TCP 是同一套协议：每条二进制消息里放的就是 TCP 的帧（##START…##END），适合浏览器和 App。ws-beta 对应 TCP 8009，ws-nightly 对应测试端口 8010。

WebSocket carries the same protocol as TCP: each binary message holds TCP frames (##START…##END), which suits browsers and apps. ws-beta maps to TCP 8009 and ws-nightly to test port 8010.

快速开始Quick start

1. 在 控制台 注册并创建一把 key（sk-sophon-…，只显示一次）。
2. POST /v2/init 创建一个角色，拿到 npcid。
3. POST /v2/login 用 npcid 换一个 TCP 令牌（JWT，4 小时有效）。
4. 连 TCP，发认证帧，收到 LISTEN start 后持续推麦克风音频，播放收到的音频。

1. Sign up in the console and create a key (sk-sophon-…, shown once).
2. POST /v2/init to create a character and get its npcid.
3. POST /v2/login to exchange the npcid for a TCP token (JWT, valid for 4 hours).
4. Connect over TCP, send the AUTH frame, and after LISTEN start stream microphone audio continuously and play what comes back.

KEY=sk-sophon-xxxxxxxx
curl -s https://api.adventists.cn/v2/init -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'
# {"code":201,"status":"success","data":"9ASU1C6e1d3ac79bab4cef8e225b0a46e2a6ac"}
curl -s https://api.adventists.cn/v2/login -H "Authorization: Bearer $KEY" -d npcid=9ASU1C6e1d3ac79bab4cef8e225b0a46e2a6ac
# {"token":"eyJhbGciOiJIUzI1NiIs..."}

完整的 Python 示例（只依赖 requests）：建角色、拿令牌、全双工连上、推一段 16 kHz 单声道 wav，打印识别结果和回复文字，把回复音频存成 reply.wav。

A complete Python example (needs only requests): create a character, get a token, connect in duplex mode, stream a 16 kHz mono wav, print the transcript and reply text, and save the reply audio to reply.wav.

import socket, threading, time, wave, requests

BASE = "https://api.adventists.cn"        # global: https://api.adventists.ai
TCP = ("api.adventists.cn", 8009)         # global: ("203.208.134.27", 8009)
KEY = "sk-sophon-..."
H = {"Authorization": f"Bearer {KEY}"}

npc = requests.post(f"{BASE}/v2/init", headers=H, json={}).json()["data"]
token = requests.post(f"{BASE}/v2/login", headers=H, data={"npcid": npc}).json()["token"]

def frame(t, payload, tid=b"duplex00", seq=0):
    return b"##START" + bytes([t]) + tid + f"{seq % 10000:04d}".encode() + payload + b"##END"

s = socket.create_connection(TCP)
s.sendall(frame(1, f"{token}##mode:duplex##format:pcm##input_audio_format:pcm##engine:tag".encode(), b"00000000"))

listening, reply = threading.Event(), bytearray()
def reader():
    buf = b""
    while (d := s.recv(65536)):
        buf += d
        while (i := buf.find(b"##START")) >= 0 and (j := buf.find(b"##END", i + 20)) >= 0:
            t, body, buf = buf[i + 7], buf[i + 20:j], buf[j + 5:]
            if t == 2: reply.extend(body)                                  # AUDIO
            elif t == 8: listening.set()                                   # LISTEN start
            elif t in (4, 5): print(t, body.decode(errors="replace"))      # TEXT / STATUS
threading.Thread(target=reader, daemon=True).start()
assert listening.wait(10), "no LISTEN start"

w = wave.open("question_16k_mono.wav"); pcm = w.readframes(w.getnframes())
n = 1920                                                    # 60 ms x 16 kHz x 2 bytes
frames = [b"\0" * n] * 16 + [pcm[i:i + n].ljust(n, b"\0") for i in range(0, len(pcm), n)] + [b"\0" * n] * 150
for k, f in enumerate(frames):                              # keep sending, silence included
    s.sendall(frame(2, f, seq=k)); time.sleep(0.06)

s.sendall(frame(5, b"##DISCONNECT", b"00000000")); time.sleep(1)
with wave.open("reply.wav", "wb") as o:
    o.setnchannels(1); o.setsampwidth(2); o.setframerate(16000); o.writeframes(bytes(reply))

5 ##INFO:认证成功，NPCID: 9ASU1C6e1d3ac79bab4cef8e225b0a46e2a6ac, 模式: duplex
5 ##INFO:prompt: 你好，你叫什么名字？
4 我是贾维斯，原名"Just A Rather Very Intelligent
4  System"，曾是托尼·斯塔克先生的人工智能助手。

示例里的解析按 ##END 切帧，便于阅读。正式客户端请按帧头定位，并把半包留到下一次 recv。

The example splits frames on ##END for readability. A production client should parse by header and keep partial frames across recv calls.

更多场景（麦克风实时对话、VAD、设备工具、会议、浏览器）见 示例代码。

More scenarios (live microphone, VAD, device tools, meetings, browser) are in Example code.

示例代码Example code

下面的示例都在国内和海外两个入口实测过，可以直接运行，也可以拷进你的项目。Key 从环境变量 ADVENTISTS_API_KEY 读，ADVENTISTS_REGION=global 切到海外入口。带 --wav 用文件代替麦克风，带 --save 把回复存成文件，没有声卡也能测试。

All examples were run against both the China and global endpoints; run them as is or copy them into your project. The key is read from ADVENTISTS_API_KEY; ADVENTISTS_REGION=global switches to the global endpoint. --wav replaces the microphone with a file and --save writes the reply to a file, so you can test without a sound card.

下载全部（zip）Download all (zip) · README

pip install requests sounddevice
export ADVENTISTS_API_KEY=sk-sophon-...
python talk_duplex.py                                   # headphones on, just talk
python talk_duplex.py --tools --emoji true              # device tools (MCP) + emoji frames
python device_tools.py --say "帮我把客厅的灯关掉"
cd ../web && python server.py                        # http://localhost:8000

浏览器和 App 接入请照 web/ 的结构：你的后端保管 key、调用 /v2/login 换令牌，前端只拿令牌连 WebSocket。

For browsers and apps follow the web/ pattern: your backend holds the key and calls /v2/login; the front end only gets the token and connects over WebSocket.

认证Authentication

所有 HTTP 接口用控制台的 key，二选一：

All HTTP APIs take a console key, in either header:

Authorization: Bearer sk-sophon-xxxxxxxx
api-key: sk-sophon-xxxxxxxx

key 自带组织信息，不需要再传 org-id。已有企业账号（32 位 api-key + 6 位 org-id）照旧可用。key 只能在服务端使用，不要写进 App 或设备固件；设备只需要拿 /v2/login 签发的令牌。

Keys carry their organization, so no org-id is needed. Existing enterprise accounts (32-char api-key + 6-char org-id) keep working. Keep keys on your server; never ship them in an app or device firmware. Devices only need the token issued by /v2/login.

每个角色的 npcid 以所属组织的 6 位 org 开头。只能给自己组织的角色签令牌、读写记忆和推送。

Every npcid starts with its organization's 6-character org ID. You can only issue tokens for, read and write memory of, and push to your own organization's characters.

模板与角色Templates and characters

模板（templateid）是一份人设配置：名字、性格、说话风格、开场白、音色、技能书、工具。角色（npcid）是从模板创建出来的一个实例，一台设备或一个用户用一个角色；记忆、知识图谱、日记都挂在角色上。修改模板不影响已创建的角色。不传 templateid 时使用默认模板（贾维斯）。也可以不用模板，直接用 templateid: "no_class" 加完整字段创建。

A template (templateid) is a persona config: name, personality, speaking style, opening line, voice, skill books and tools. A character (npcid) is an instance created from a template, typically one per device or end user; memory, the knowledge graph and the diary belong to the character. Editing a template does not change characters already created. Without a templateid the default template (Jarvis) is used. You can also skip templates and create with templateid: "no_class" plus the full set of fields.

可以把模板理解成「类」，角色是「实例」：1000 个用户用同一个模板，就创建 1000 个角色。模板记忆（用 save_template_memory 灌入）由所有角色共享；每个角色和自己用户的对话记忆互相独立。不要让多个用户共用一个 npcid，否则记忆会串。想重置一个角色，就从同一模板重新创建一个。公共模板（如 LuLu、Sakura、曹操）可以用 public_template_list 查到。

Think of a template as a class and a character as an instance: 1,000 users on one template means 1,000 characters. Template memory (loaded with save_template_memory) is shared by all of them; each character's memory of its own user is separate. Never share one npcid across users, or their memories mix. To reset a character, create a new one from the same template. Public templates (LuLu, Sakura, Cao Cao…) are listed by public_template_list.

POST /v2/init · POST /v2/login

POST /v2/template

一个接口，用 action 区分操作，body 为 JSON。返回 {"code":200,"status":"success","data":…}。

One endpoint; action selects the operation. JSON body. Returns {"code":200,"status":"success","data":…}.

curl -s https://api.adventists.cn/v2/template -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "action": "create_template", "name": "小安", "mbti_type": "ENFJ", "love_type": "Virgo",
  "person": "你是一个陪伴型桌面机器人……", "style": "简短亲切", "emotion_system": "开心时语气轻快",
  "start_speech": "你好呀！", "temp": "0.5",
  "voice_id": "xiaonanhai", "functions": ["get_weather", "search_internet"]}'

POST /v2/npc

角色字段Character fields

创建模板和 no_class 角色时，name、person、style、emotion_system、mbti_type、love_type 必填，其余可选。

When creating a template or a no_class character, name, person, style, emotion_system, mbti_type and love_type are required; the rest are optional.

实时语音：连接与帧格式Realtime voice: connection and frames

TCP 长连接（不是 WebSocket）。连接后 5 秒内要发认证帧；300 秒没有任何数据会被断开。所有消息都是同一种帧：

A plain TCP connection (not WebSocket). Send the AUTH frame within 5 seconds of connecting; the server closes connections idle for 300 seconds. Every message uses the same frame:

##START  [type 1 byte]  [task_id 8 bytes ASCII]  [seq 4 bytes ASCII, 0000–9999]  [payload]  ##END

task_id 由客户端定义，固定 8 字节；00000000 保留给系统消息（认证、心跳、断开）。duplex 模式下整场会话固定用 duplex00。

task_id is client-defined, exactly 8 bytes; 00000000 is reserved for system messages (auth, heartbeat, disconnect). In duplex mode use duplex00 for the whole session.

认证帧参数AUTH parameters

##START\x01 00000000 0000 <token>##mode:duplex##format:pcm##input_audio_format:pcm##engine:tag##END

（空格只是为了好读，实际没有空格。）参数用 ##名称:值 跟在令牌后面，顺序随意，不认识的参数会被忽略。

(Spaces added for readability; there are none on the wire.) Parameters follow the token as ##name:value in any order; unknown parameters are ignored.

认证结果通过 STATUS 返回：成功 ##INFO:认证成功，NPCID: <npcid>, 模式: duplex，失败 ##ERROR:token error 并断开。

The result comes back as STATUS: success is ##INFO:认证成功，NPCID: <npcid>, 模式: duplex ("authenticated"); failure is ##ERROR:token error followed by a disconnect.

三种对话模式Conversation modes

duplex

1. 认证帧带 ##mode:duplex。
2. 等服务端发 LISTEN start（type 8，约 1 秒内，整场只发这一次）：{"taskid":"duplex00","type":"listen","state":"start","mode":"duplex"}。在这之前推的音频不保证被处理。
3. 之后一直按 60 ms 一帧推音频，没人说话时也要推静音，断流会被当成没有输入。
4. 收下行：AUDIO 边收边播；TEXT 是刚说完那句的文字记录；STATUS 里 ##INFO:prompt:… 是识别出的用户原话；END 表示一段回复结束。
5. 用户随时说话就是打断，客户端什么都不用做。客户端发 LISTEN 会被忽略（回 ##INFO:LISTEN start ignored in duplex mode），发 SPEAK 会回 ##ERROR。

1. Send ##mode:duplex in the AUTH frame.
2. Wait for the server's LISTEN start (type 8, within about a second, sent only once per session): {"taskid":"duplex00","type":"listen","state":"start","mode":"duplex"}. Audio sent before it may be dropped.
3. Then stream 60 ms audio frames continuously, including silence when nobody speaks; a gap in the stream is treated as no input.
4. Downstream: play AUDIO as it arrives; TEXT is a transcript of what was just said; STATUS ##INFO:prompt:… is the recognized user speech; END marks the end of a reply segment.
5. The user can barge in at any time just by talking; the client does nothing. Client LISTEN frames are ignored (##INFO:LISTEN start ignored in duplex mode) and SPEAK returns ##ERROR.

auto (VAD)

1. 认证帧带 ##mode:auto。
2. 客户端为这一轮选一个 task_id，发 LISTEN start：##START\x08task00010000{"type":"listen","state":"start"}##END，服务端回 ##INFO:开始监听，task_id: task0001。
3. 用这个 task_id 持续推音频，不需要发 END。服务端检测到说话发 {"state":"detecting"}，检测到说完发 {"state":"stop"}（都是 type 8），然后返回识别结果、回复文字和音频、END。
4. 下一轮换一个新的 task_id 再发 LISTEN start。要在角色说话时打断，发 {"type":"listen","state":"start","interrupt":true}。旧 task_id 的音频帧会被丢弃。
5. 只有噪音时服务端回 ##INFO: 提示并继续听。

1. Send ##mode:auto in the AUTH frame.
2. The client picks a task_id for the turn and sends LISTEN start: ##START\x08task00010000{"type":"listen","state":"start"}##END. The server replies ##INFO:开始监听，task_id: task0001 ("listening").
3. Stream audio with that task_id; no END needed. The server sends {"state":"detecting"} when speech starts and {"state":"stop"} when it ends (both type 8), then the transcript, reply text and audio, and END.
4. For the next turn use a new task_id and send LISTEN start again. To interrupt the character mid-reply send {"type":"listen","state":"start","interrupt":true}. Frames with an old task_id are dropped.
5. If only noise is heard the server sends an ##INFO: hint and keeps listening.

manual

按键说话：用一个 task_id 推完这段音频（seq 从 0000 递增），再发 ##START\x03task0001<seq>##END。服务端返回 ##INFO:prompt:…、TEXT、AUDIO，最后 END。下一轮换新的 task_id。

Push-to-talk: send the utterance's audio with one task_id (seq counting up from 0000), then ##START\x03task0001<seq>##END. The server returns ##INFO:prompt:…, TEXT, AUDIO and finally END. Use a new task_id for the next turn.

音频格式Audio formats

上行和下行的格式分别由 input_audio_format 和 format 控制，可以不同。

Upstream and downstream are set separately by input_audio_format and format and may differ.

文本、SPEAK 与状态消息Text, SPEAK and status messages

文字输入（manual / auto）：##START\x04task0001 0000 你好##END 后跟 ##START\x03task0001 0001##END，角色会像听到这句话一样回复（有声音）。

Text input (manual / auto): ##START\x04task0001 0000 hello##END followed by ##START\x03task0001 0001##END; the character replies, with audio, as if it had heard the sentence.

SPEAK（manual / auto）：##START\x07speak001 0000 欢迎回家##END，不经过模型，直接用角色音色念出来，返回 TEXT、AUDIO、END。

SPEAK (manual / auto): ##START\x07speak001 0000 Welcome home##END skips the model and reads the text in the character's voice, returning TEXT, AUDIO and END.

魔法命令Magic commands

用户在对话里说出（或用 TEXT 发送）下面的话，会切换会话行为，角色回一句确认：

When the user says (or sends as TEXT) one of these phrases, the session behaviour changes and the character confirms:

设备工具（MCP）Device tools (MCP)

设备可以把自己的能力（开灯、调音量、拍照…）注册给角色，角色在对话中需要时会调用。所有消息用 type 0x06，task_id 建议 mcp00001，认证成功后随时可以注册或重新注册。

Devices can register their own capabilities (lights, volume, camera…) and the character calls them when needed. All messages use type 0x06; task_id mcp00001 is recommended. Register (or re-register) any time after auth.

// C→S register
{"type":"register","data":{"services":{"light_control":{
  "description":"控制房间的灯 / Turn room lights on or off",
  "parameters":{"type":"object","properties":{
    "room":{"type":"string","description":"房间"},
    "state":{"type":"string","enum":["on","off"]}},"required":["room","state"]}}}}}
// S→C call
{"type":"call","data":{"call_id":"c-123","method":"light_control","params":{"room":"客厅","state":"off"}}}
// C→S result (same call_id)
{"type":"result","data":{"call_id":"c-123","result":{"success":true,"data":"客厅的灯已关"}}}

参数用 JSON Schema 描述；描述写清楚，模型才知道什么时候该调用。失败时返回 {"success":false,"error":"…"}，角色会把失败告诉用户。

Parameters use JSON Schema; clear descriptions help the model decide when to call. On failure return {"success":false,"error":"…"} and the character tells the user.

表情Emoji

认证帧加 ##emoji_mode:true，服务端会随回复下发 EMOJI 帧（type 9）：{"emoji":"happy"}，设备据此播放表情动画。

Add ##emoji_mode:true to the AUTH frame and the server sends EMOJI frames (type 9) with replies, e.g. {"emoji":"happy"}, for the device to animate.

图片与视觉Images and vision

让角色看见（全双工 duplex）：图片会直接交给正在说话的模型，角色当场看着画面回答，例如“我手里拿的是什么”。有两种发法，效果相同：

Let the character see (full-duplex): images go straight to the model that is speaking, so the character answers from the picture right away (“what am I holding?”). Two ways to send them, same result:

① 推荐：在语音连接里直接发图片帧。上行 IMAGE 帧（type 0x0a），载荷是 JPEG 二进制。一张图按每片不超过 1012 字节切开，同一张图的分片用同一个 task_id（如 img00001），seq 从 0000 递增；最后一片以 JPEG 结束标记 FF D9 结尾，服务端收到就算一张完整的图。

① Recommended: send image frames on the voice connection. Uplink IMAGE frames (type 0x0a) carry raw JPEG bytes. Split one image into chunks of at most 1012 bytes, give all chunks of the same image the same task_id (e.g. img00001) with seq counting up from 0000; the image is complete when a chunk ends with the JPEG end marker FF D9.

##START + [0x0a] + "img00001" + "0000" + <JPEG bytes 0–1011>    + ##END
##START + [0x0a] + "img00001" + "0001" + <JPEG bytes 1012–2023> + ##END
…  (last chunk ends with FF D9)

• 建议长边不超过 448 px、JPEG 质量 70 左右（20–40 KB），最多每秒 1 张。
• 分片要夹在音频帧之间发，不要一口气连发，免得挤住上行音频；单张上限 400 KB。

• Keep the long side at 448 px or less, JPEG quality around 70 (20–40 KB), at most one image per second.
• Interleave the chunks between audio frames rather than sending them in one burst, so they never hold up the audio; 400 KB per image at most.

② 兼容：HTTP 上传。原来的接口不变，通话进行中上传的图 1 秒内也会送进模型：

② Compatible: HTTP upload. The existing endpoint still works; an image uploaded during a call reaches the model within a second:

POST /v2/upload_image
{"npcid": "<npcid>", "image": "<base64 JPEG, without the data:image/... prefix>"}
→ {"status": "ok", "path": "…"}

请以返回体里的 status 判断成功与否，不要只看 HTTP 状态码。也可以直接传文件：POST /v2/upload_image_file，multipart 字段 pic_file（图片文件）和 npcid。auto / manual 模式只支持 HTTP 上传。

Check the status field in the body rather than only the HTTP code. To upload a file instead: POST /v2/upload_image_file with multipart fields pic_file and npcid. The auto / manual modes support HTTP upload only.

什么时候发：每张图 10 秒内有效，过了 10 秒角色就不再认为自己看得到画面。

• 按需看（默认推荐）：注册一个名字里带 take_photo 的设备工具（如 take_photo、take_photo_upload）。用户说“看看这是什么”时角色会调用它；设备拍一张，用图片帧（或 /v2/upload_image）发上来，再回执 {"success": true}。
• 一直看（视频通话）：开着摄像头时每秒发 1 帧。这种模式应由用户主动打开，设备上要有明显的摄像头指示。

When to send: each image counts for 10 seconds; after that the character no longer assumes it can see.

• On demand (recommended default): register a device tool whose name contains take_photo (e.g. take_photo, take_photo_upload). When the user says “look at this”, the character calls it; the device takes one picture, sends it as image frames (or via /v2/upload_image), then replies {"success": true}.
• Continuous (video call): send one frame per second while the camera is on. Let the user turn this mode on explicitly and show a clear camera indicator on the device.

角色画图或推图片：服务端下发 IMAGE 帧（type 0x0a）{"type":"image","url":"…"}，客户端 GET 这个地址显示即可。认证时声明了 resolution 的话，图片已按屏幕尺寸等比缩放。画图工具统一用 draw_pic / draw_pic_google（旧的 _t / _d 后缀已合并）。不认识 type 0x0a 的旧客户端会忽略它。

Images from the character (drawings or pushes) arrive as IMAGE frames (type 0x0a) {"type":"image","url":"…"}; GET the URL and display it. If you declared resolution at auth, the image is already scaled to fit. The drawing tools are draw_pic / draw_pic_google (the old _t / _d variants were merged). Older clients that don't know type 0x0a simply ignore it.

会议模式Meeting mode

设备当会议记录仪用：实时转写、字幕整理和翻译、会后区分说话人并生成纪要。认证帧：

Use the device as a meeting recorder: live transcription, cleaned-up and translated captions, and after the meeting speaker labels and minutes. AUTH frame:

<token>##session_type:meeting##mode:vad##device_id:<id>##caption_target_lang:zh##caption_mode:bilingual

下行 STATUS 里会有 ##TRANSCRIPT:…（逐句转写）、##CAPTION_INTERIM:…（未定稿字幕，整行替换）、##CAPTION_FINAL:…（定稿字幕）。会议相关的 HTTP 接口：

Downstream STATUS carries ##TRANSCRIPT:… (per-sentence transcripts), ##CAPTION_INTERIM:… (draft caption, replace the whole line) and ##CAPTION_FINAL:… (final caption). Meeting HTTP APIs:

音色与克隆Voices and cloning

样本建议 10–30 秒、单人、无背景音乐和回声；同一段话复制拼接的音频会被拒绝。

Use 10–30 s of a single speaker without music or echo; audio made by repeating the same clip is rejected.

试听与批量合成Preview and batch synthesis

技能书Skill books

技能书是给角色的专属知识库（产品手册、FAQ、故事集…）。流程：创建 → 上传文件 → 标记就绪 → 等学习完成 → 把 skill_id 写进模板或角色的 skill_ids。

A skill book is a private knowledge base for a character (manuals, FAQs, stories…). Flow: create → upload files → mark ready → wait for learning → add the skill_id to a template's or character's skill_ids.

记忆（Hippo）Memory (Hippo)

角色会自动记住对话，并在后台整理出个人知识图谱（PKG）、关系和日记。这些接口用于读取、补充或修正。路径里的 {npcid} 必须属于你的组织。

Characters remember conversations automatically and, in the background, distill a personal knowledge graph (PKG), relationships and a diary. These APIs read, add to or correct them. {npcid} must belong to your organization.

PKG 单值字段（覆盖写入）：Name（已有则不覆盖）Gender Age Occupation City Location Timezone Description Relationship "Favorite Food" Philosophy Father Mother other profile。多值字段（去重追加）：Nickname(5) "Favorite Sports" "Favorite Books" "Favorite Movies" Hobbies(各 10)。字段名不区分大小写。

PKG single-value fields (overwrite): Name (not overwritten once set), Gender, Age, Occupation, City, Location, Timezone, Description, Relationship, "Favorite Food", Philosophy, Father, Mother, other, profile. Multi-value fields (deduplicated append): Nickname (5), "Favorite Sports", "Favorite Books", "Favorite Movies", Hobbies (10 each). Field names are case-insensitive.

用量统计Usage statistics

GET /v2/statistics?startTime=<ms>&endTime=<ms>&granularity=DAILY&npcId=…&deviceId=…

按天（DAILY）或按月（MONTHLY）返回本组织的对话次数和 token 用量，可按角色或设备过滤；时间是毫秒时间戳，跨度最多 30 天。返回 records[]，每项含 period、callCount、inputToken、outputToken、totalToken。

Your org's conversation count and token usage per day (DAILY) or month (MONTHLY), optionally filtered by character or device. Times are millisecond timestamps, up to 30 days apart. Returns records[] with period, callCount, inputToken, outputToken, totalToken.

封禁Blocking

封禁某台设备或某个角色后，它将无法再建立对话。

A blocked device or character can no longer start conversations.

设备推送Device push

从你的服务端给在线设备发消息（播报、通知、进度）。设备离线时，speak / text / info 会排队，设备重连后送达。

Send messages from your server to an online device (announcements, notices, progress). If the device is offline, speak / text / info are queued and delivered on reconnect.

POST /push/api/push
{"npcid":"<npcid>","type":"speak","payload":{"text":"你的快递到了"},
 "priority":"normal","callback_url":"https://your.server/hook","task_id":"optional-id"}
→ 200 {"ok":true,"task_id":"a1b2c3d4","status":"delivered"}
→ 202 {"ok":true,"task_id":"a1b2c3d4","status":"queued","queue_position":1}

priority：urgent / high / normal / low。查询任务状态：GET /push/api/tasks/{task_id}。只能推给本组织的角色，否则 403。

priority: urgent / high / normal / low. Task status: GET /push/api/tasks/{task_id}. You can only push to your own characters (403 otherwise).

旧接口 POST /push/api/speak（{"npcid","text"}）仍可用，等同 type=speak。

The legacy POST /push/api/speak ({"npcid","text"}) still works and equals type=speak.

日志推送Log webhook

每轮对话或后台记忆任务结束后，把 token 用量和对话内容 POST 到你的地址，用于对账或自己的数据分析。用 POST /v2/log_config 管理，body 里的 action 取：

After each conversation turn or background memory task, we POST token usage and content to your URL for reconciliation or analytics. Manage it with POST /v2/log_config, where action is:

推送类型：llm_log（每轮对话，含 npcid、device_id、inputToken、outputToken、prompt、answer、各阶段耗时）、dream_log / flush_log（后台记忆任务）。wrap=true 时格式为 {"type":"llm_log","data":{…}}。不配 template 会推送完整内容（包括对话原文）；配了 template 只推映射后的字段，适合只要 token 用量的计费平台。template 支持字段改名，以及 const、uuid、now、datetime、sum、field 规则。

Payload types: llm_log (each turn: npcid, device_id, inputToken, outputToken, prompt, answer, per-stage timings) and dream_log / flush_log (background memory tasks). With wrap=true the body is {"type":"llm_log","data":{…}}. Without a template the full payload, including conversation text, is sent; with a template only mapped fields are sent, which suits billing platforms that need token counts only. Templates support field renames and the rules const, uuid, now, datetime, sum, field.

{"action":"update_webhook","fields":{
  "log_webhook_url":"https://your.server/llm-log",
  "log_webhook_headers":{"Authorization":"Bearer your-token"},
  "log_webhook_template":{"upstream_tokens":"inputToken","downstream_tokens":"outputToken",
    "total":{"type":"sum","sources":["inputToken","outputToken"]},"platform":{"type":"const","value":"my-app"},
    "ts":{"type":"now"},"sent_at":{"type":"datetime","source":"timestamp"}}}}
→ {"status":"success","data":{"updated":["log_webhook_url","log_webhook_headers","log_webhook_template"]}}

错误与常见问题Errors and FAQ

很多 /v2 接口失败时 HTTP 仍是 200，请同时检查返回体里的 status / code。

Many /v2 endpoints return HTTP 200 on failure too; also check status / code in the body.

认证成功但没有回复？ duplex 要先等 LISTEN start，并持续推音频（包括静音）；auto 要先由客户端发 LISTEN start；manual 要发 END。录音末尾没有静音时，服务端无法判断你说完了。

Authenticated but no reply? In duplex, wait for LISTEN start and keep streaming (silence included). In auto, the client must send LISTEN start first. In manual, send END. Without trailing silence the server cannot tell you have finished.

断线了怎么办？ 重新连接并发认证帧；令牌过期就先调 /v2/login。

Disconnected? Reconnect and send AUTH again; call /v2/login first if the token expired.

用量和计费：Harness 的用量目前不在控制台的「用量」页里显示，按合同结算。按天 / 按月的 token 用量可查 /v2/statistics，逐轮明细可配置日志推送。

Usage and billing: Harness usage is not yet shown on the console's Usage page and is settled per contract. Daily / monthly token usage is at /v2/statistics; for per-turn detail configure the log webhook.

变更记录Changelog

• 2026-11-14：全双工下图片直接交给说话的模型：新增上行 IMAGE 帧（type 0x0a，JPEG 分片）；通话中经 /v2/upload_image 上传的图也会实时送进模型；名字含 take_photo 的设备工具拍完照会自动看图。
• 2026-11-13：文档迁到控制台，取代原 Apifox 文档。新增 sk-sophon- key 认证（不再需要 org-id）；统一入口为 api.adventists.cn / api.adventists.ai，海外新增 WebSocket 入口 wss://api.adventists.ai/ws-beta，记忆和推送分别在 /hippo/、/push/ 下；TCP 认证帧新增 engine 参数；海外 TCP 入口改为 203.208.134.27:8009。
• v2.5：duplex 全双工模式、auto（VAD）模式、设备工具（MCP）、SPEAK、上行 Opus、IMAGE 帧与 resolution、会议模式与实时字幕翻译。
• 2026-10-01：会议纪要 2.1——流式转写、生成进度与预计耗时、讲座 / 读书会模板、按 npcid 查历史会议、录音下载（保留 7 天）。
• 2026-09-07：魔法命令 incognito on/off（无痕模式）。
• 2026-06-02：IMAGE 帧（0x0a）与 resolution 参数；画图函数统一为 draw_pic / draw_pic_google。
• 2026-04：Hippo 记忆接口、封禁接口、denoise 降噪、角色字段 intent_extensions。
• 2025-10：hotword 热词；VAD 新增 detecting 状态（用户开始说话，可借此停止播放实现打断）；emoji_mode；debug on/off。
• 2025：SPEAK 消息（v2.4）、上行 Opus（v2.4.1）、下行 PCM / Opus 可选（v2.2）；连接空闲超时 5 分钟、认证超时 5 秒。

• 2026-11-14: in full-duplex, images now go straight to the speaking model: new uplink IMAGE frames (type 0x0a, chunked JPEG); images uploaded with /v2/upload_image during a call reach the model live; device tools named take_photo* automatically look at the picture they took.
• 2026-11-13: Docs moved into the console, replacing the old Apifox site. Added sk-sophon- key auth (no org-id needed); unified entry points api.adventists.cn / api.adventists.ai (plus WebSocket at wss://api.adventists.ai/ws-beta), with memory and push under /hippo/ and /push/; new engine AUTH parameter; global TCP entry is 203.208.134.27:8009.
• v2.5: duplex mode, auto (VAD) mode, device tools (MCP), SPEAK, Opus upstream, IMAGE frames and resolution, meeting mode with live caption translation.
• 2026-10-01: Meeting minutes 2.1 — streaming transcripts, progress and ETA, lecture / reading-group templates, meeting history by npcid, recording download (kept 7 days).
• 2026-09-07: magic command incognito on/off.
• 2026-06-02: IMAGE frame (0x0a) and resolution; drawing tools unified as draw_pic / draw_pic_google.
• 2026-04: Hippo memory and blocking APIs, denoise, intent_extensions field.
• 2025-10: hotword; VAD detecting state (user started talking — stop playback for barge-in); emoji_mode; debug on/off.
• 2025: SPEAK (v2.4), Opus upstream (v2.4.1), PCM / Opus downstream (v2.2); 5-minute idle timeout, 5-second auth timeout.