接入文档
活水模型本机服务的全部接口:地址、密钥,以及每种能力该调哪个端点、怎么写请求。
活水模型在本机起一个服务(桌面版开着就在,命令行用 42model serve),别的程序按下面的接口调它。每节都给一条能直接复制的 curl。
地址与密钥
- 地址:
http://localhost:11520 - 密钥:默认是
42model。放在请求头Authorization: Bearer 42model或x-api-key: 42model里都行,不带会被拒(401)。 - 换一把专属密钥:在桌面版「接入」页生成,或运行
42model config set api-key generate,再42model serve restart。换了之后,下面例子里的42model都换成你的新密钥。 - model 怎么填:填模型的名字,比如
qwen3.5:9b-q4_k_m(在桌面版模型卡上、或42model list里能看到);不写就用这项能力在本机的默认模型。
curl http://localhost:11520/v1/models -H "Authorization: Bearer 42model"
通用 · 翻译 · 写作 · 科研 · 视觉理解
这几项都走同一个端点 POST /v1/chat/completions,格式与 OpenAI 相同,"stream": true 可以边生成边返回。区别只在 model 填哪个、消息怎么写(长文翻译另有专用接口,见「翻译」)。也可以按 Anthropic 的格式调 POST /v1/messages,两种格式背后是同一个模型、同一套参数。
通用
curl http://localhost:11520/v1/chat/completions \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.5:9b-q4_k_m",
"messages": [{"role": "user", "content": "用一句话介绍你自己。"}]
}'
Anthropic 格式:
curl http://localhost:11520/v1/messages \
-H "x-api-key: 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.5:9b-q4_k_m",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "用一句话介绍你自己。"}]
}'
- 数 token 用
POST /v1/messages/count_tokens(请求体同上,不用写max_tokens;含图的消息不支持,回 400,code为count_tokens_images_unsupported)。Claude Code 这类工具把地址指过来就能用,见接入 Claude Code / Codex。 - 思考:
"thinking": {"type": "enabled", "budget_tokens": 8000}开思考,{"type": "disabled"}关。budget_tokens按区间对应思考强度:1024–4095 为 low,4096–15999 为 medium,16000–31999 为 high,32000 及以上为 xhigh;与 OpenAI 格式的reasoning_effort同一套档位。budget_tokens至少 1024,且要小于max_tokens,否则回 400。 - OpenAI Responses:
POST /v1/responses。每次请求自带完整上下文,服务端不保存对话。
翻译
长文用 POST /v1/translate。翻译模型一次读太长会提前收尾、只译开头一部分,这个接口会按段落、行、句把原文切成小块逐块翻,再按原文的分段拼回,段落对得上。OpenAI 没有翻译标准,这是活水模型自己的接口,和 OCR 一样没有 Anthropic 写法。
curl http://localhost:11520/v1/translate \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "hy-mt2:7b-q4_k_m",
"text": "今天的会改到下午三点。\n\n请大家提前十分钟到。",
"target": "en"
}'
target是目标语言代码,比如en、zh、ja;可选哪些看模型,写了模型不支持的语言回 400(code为translate_target_unsupported,提示里列出可选的)。model必须是翻译模型,不写就用本机默认的翻译模型。- 返回
text(整篇译文)、truncated(有没有哪一块撞到输出上限)、segments(切成了几块)和速度读数timings。 "stream": true边翻边返回:每行一个data: {"type": "delta", "text": …},最后是{"type": "done", …},字段同上;出错是{"type": "error", …},随即结束。- 命令行:
42model run hy-mt2:7b-q4_k_m - --to en < 文章.txt,走的是同一个接口。
短句也可以直接走 /v1/chat/completions,目标语言写在消息里(Anthropic 格式 POST /v1/messages 同理,写法同「通用」)。原文长了不要这样调,会只译出开头一部分:
curl http://localhost:11520/v1/chat/completions \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "hy-mt2:7b-q4_k_m",
"messages": [{"role": "user", "content": "把下面的文本翻译成英语,不要额外解释。\n\n今天的会改到下午三点。"}]
}'
写作
model 填写匠校对模型 aiwriter-check:v1-preview-q8_0(小一档是 aiwriter-check:v1-preview-q5_k_m)。消息里直接放要校对的文字,它返回改好的那段;没错的句子原样返回。
curl http://localhost:11520/v1/chat/completions \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "aiwriter-check:v1-preview-q8_0",
"messages": [{"role": "user", "content": "并做出了相映的调整。"}]
}'
Anthropic 格式:POST /v1/messages,写法同「通用」里的例子,换上这里的 model 和消息即可。
科研
model 填科研模型,比如能看图、擅长化学结构与蛋白序列的 intern-s1:mini-q8_0。它会先思考再作答,回答比通用模型慢一些。
curl http://localhost:11520/v1/chat/completions \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "intern-s1:mini-q8_0",
"messages": [{"role": "user", "content": "苯环为什么特别稳定?用三句话说明。"}]
}'
Anthropic 格式:POST /v1/messages,写法同「通用」里的例子,换上这里的 model 和消息即可。
视觉理解
model 填能看图的模型:qwen3.5:2b-q8_0、qwen3.5:4b-q4_k_m、qwen3.5:9b-q4_k_m、qwen3.6:27b-q4_k_m。图片放在 image_url 里,只收 base64,不收网址:
IMG=$(base64 -i 截图.png)
curl http://localhost:11520/v1/chat/completions \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.5:9b-q4_k_m",
"messages": [{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "data:image/png;base64,'"$IMG"'"}},
{"type": "text", "text": "图里写了什么?"}
]
}]
}'
- 看视频:把
image_url换成video_url,地址写data:video/mp4;base64,…。一次只放一段视频、不和图片混在一起,最长 2 分钟,目前只支持 Mac。
Anthropic 格式:图片用 base64 的 image 块,同样不收网址。
IMG=$(base64 -i 截图.png)
curl http://localhost:11520/v1/messages \
-H "x-api-key: 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.5:9b-q4_k_m",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "'"$IMG"'"}},
{"type": "text", "text": "图里写了什么?"}
]
}]
}'
- 看视频用 OpenAI 格式。
语音
转录
POST /v1/audio/transcriptions,格式与 OpenAI 相同:表单上传音频文件。
curl http://localhost:11520/v1/audio/transcriptions \
-H "Authorization: Bearer 42model" \
-F file=@录音.wav \
-F model=qwen3-asr:1.7b-q8_0
- 返回
{"text": …};-F response_format=text只要纯文字。 - 可选
-F language=zh指定语言;-F prompt=人名、术语给几个容易认错的词。
Anthropic 格式:没有,用上面的 OpenAI 格式。
语音合成
POST /v1/audio/speech,格式与 OpenAI 相同:给一段文字,返回朗读的 WAV。
curl http://localhost:11520/v1/audio/speech \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{"input": "你好,欢迎使用活水模型。", "language": "zh"}' \
-o 朗读.wav
model可省,省了用本机语音合成的默认模型;language可选,填zh、en等。- 目前只有一种声音:
voice可以照 OpenAI 的写法带上,但不影响结果;response_format只支持wav;speed、instructions暂不支持,带了会报错。 - 声音边合成边返回;长文字按句分段合成,整条仍是一个 WAV。一次最多 2 万字,超了报「文字太长,请分批合成」。
Anthropic 格式:没有,用上面的 OpenAI 格式。
OCR
POST /v1/ocr。OpenAI 没有 OCR 标准,这里用表单上传图片,和语音转录一样。
curl http://localhost:11520/v1/ocr \
-H "Authorization: Bearer 42model" \
-F file=@扫描页.png \
-F model=glm-ocr:1b-q8_0
- 返回
text(纯文本)和markdown(表格以 HTML 表格嵌入)。 -F task=spotting改成逐行识别,每行带它在原图上的位置(segments[].bbox);支持的模型有hyocr-1.5:q8_0、pp-ocrv6:medium等。- 一次识别几页:重复
-F file=@…。不收 PDF,先把 PDF 转成图片。 - 整份长文档:一页发一个请求,加
-F long_doc=true -F page_index=<从 0 数的页号> -F total_pages=<总页数>,从第二页起把上一页返回的state原样带上(-F state=…),模型就能接上跨页的标题和表格。
Anthropic 格式:POST /v1/messages,model 写 OCR 模型(或 default:ocr),图片放在 base64 的 image 块里(几张就是几页)。返回一个 text 块,内容与上面 markdown 字段相同;usage 是按页数和字数估的,不是分词器算的。不收 document(PDF)块。max_tokens 照常要写正整数,但识别长度按模型的识别额度走,不按它截。
IMG=$(base64 -i 扫描页.png)
curl http://localhost:11520/v1/messages \
-H "x-api-key: 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-ocr:1b-q8_0",
"max_tokens": 4096,
"messages": [{"role": "user", "content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "'"$IMG"'"}}
]}]
}'
制图
POST /v1/images/generations,格式与 OpenAI 相同:写一句描述,返回一张 PNG。目前只支持 Mac。
curl http://localhost:11520/v1/images/generations \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{"model": "z-image", "prompt": "清晨的江南小镇,石桥,薄雾", "size": "1024x1024"}' \
| python3 -c 'import sys, json, base64; open("图.png", "wb").write(base64.b64decode(json.load(sys.stdin)["data"][0]["b64_json"]))'
- 返回
{"created": …, "data": [{"b64_json": …}]},b64_json是 PNG 的 base64。只出 base64,不给图片网址:response_format不写或写b64_json,写url会回 400;output_format不写或写png,别的格式也回 400。 model不写就用z-image。size写成宽x高:宽和高都在 256 到 4096 之间,并且是 64 的倍数;不写或写auto用模型的默认尺寸。prompt必填,最多 4000 字。n只能是 1,一次一张。- 可选
seed固定随机种子:同一台电脑上,同一个种子、同一句描述、同一个尺寸,出同一张图。 - 一张图要几十秒到几分钟。同一时刻只画一张:前一张还没画完时再发,会立刻收到 429,按响应头
Retry-After的秒数过一会儿再试。 - 描述和出的图都要过内容检查,不合适的会被拒(400)。生成的图片带 AI 生成标识。
- 上面那段命令只在出图成功时能存下图片;出错时返回的是
{"error": {"code": …, "message": …}},那句 python 会报错,去掉| python3 …那一行就能看到原因。
出错时按 error.code 处理:
| 状态 | code | 怎么办 |
|---|---|---|
| 400 | invalid_prompt / invalid_size / invalid_n | 照报错改:描述空了或太长、尺寸不合规则、n 不是 1 |
| 400 | unsupported_response_format / unsupported_output_format | 去掉这两个字段,或写成 b64_json、png |
| 400 | model_not_found | model 写错了,换成模型库里的名字 |
| 400 | model_not_image | 这个模型不能出图(比如对话模型),换一个制图模型 |
| 400 | model_not_downloaded | 制图模型还没下载,先在模型库里下载 |
| 400 | content_blocked | 描述或出的图没过内容检查,换一句描述 |
| 429 | image_busy / image_cooldown | 按 Retry-After 的秒数过一会儿再试 |
| 503 | memory_busy | 内存此刻被别的模型占着,按 Retry-After 过一会儿再试 |
| 502 | image_failed | 这次没出图,详情在引擎日志里(42model log open) |
检索
POST /v1/embeddings,格式与 OpenAI 相同:把文字变成向量,做相似度检索。
curl http://localhost:11520/v1/embeddings \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3-embedding:0.6b-q8_0", "input": ["第一段文字", "第二段文字"]}'
input 可以是一段文字,也可以是一组(一次最多 256 段)。
Anthropic 格式:没有,用上面的 OpenAI 格式。
决策
POST /v1/systemone:给背景和几道题,模型给每个选项的概率,不生成文字。
curl http://localhost:11520/v1/systemone \
-H "Authorization: Bearer 42model" \
-H "Content-Type: application/json" \
-d '{
"model": "vllm-d3:mini-q4_k_m",
"state": "主角已经三章没出场了。",
"questions": {
"answer": {
"type": "choice",
"instructions": "这一章要不要把主角加回来?",
"criteria": { "加回主角": null, "继续写配角": null }
}
}
}'
model:vllm-d3:nano-q8_0、vllm-d3:mini-q4_k_m、vllm-d3:flash-q4_k_m、vllm-d3:27b-q4_k_m;不写就用本机的默认那款。state:背景,没有就写null。questions:一次可以问好几道题,每道题的type选一种:choice:选一个,选项写进criteria,后面可以附一句说明,没有说明写null;score:打分,criteria写一个从低到高的数组,比如["差", "一般", "好"];noul:是 / 否,不用写选项。
- 返回的
answers下按题列出答案:选一个题给出选中的那项、每项的概率和置信度confidence(0–1,越接近 1 越肯定)。
Anthropic 格式:没有,用上面的 OpenAI 格式。
其他
GET /v1/models:本机已装好的模型,每个带名字、类别、大小。GET /v1/abilities:本机每项能力能不能用、默认用哪个模型,与42model abilities相同。POST /v1/diarize:整段录音分出谁在说话。表单上传file(音频),model填增强版转录模型qwen3-asr-plus:1.7b。GET /health:服务在不在,不用带密钥。