活水模型
返回文档
接入

接入文档

活水模型本机服务的全部接口:地址、密钥,以及每种能力该调哪个端点、怎么写请求。

活水模型在本机起一个服务(桌面版开着就在,命令行用 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怎么办
400invalid_prompt / invalid_size / invalid_n照报错改:描述空了或太长、尺寸不合规则、n 不是 1
400unsupported_response_format / unsupported_output_format去掉这两个字段,或写成 b64_json、png
400model_not_foundmodel 写错了,换成模型库里的名字
400model_not_image这个模型不能出图(比如对话模型),换一个制图模型
400model_not_downloaded制图模型还没下载,先在模型库里下载
400content_blocked描述或出的图没过内容检查,换一句描述
429image_busy / image_cooldown按 Retry-After 的秒数过一会儿再试
503memory_busy内存此刻被别的模型占着,按 Retry-After 过一会儿再试
502image_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:服务在不在,不用带密钥。