WorkBuddy 接入

本文带你完成 WorkBuddy 的本站接入：先配置文本模型，再按需让 WorkBuddy 调用图片或视频接口。已有截图以 WorkBuddy V5.8.3 为例；不同版本的按钮位置可能略有变化，字段含义与本站接口地址保持一致。

1. 接入前的准备

1.1 创建一把 WorkBuddy 专用密钥

登录本站，进入 API 密钥，点击「创建密钥」，名称可填写 WorkBuddy，然后复制完整密钥。

• 只使用文本模型时，可将密钥绑定到「文字模型」分组。

• 还要调用图片或视频模型时，需要使用有相应模型权限的密钥。可以分别创建密钥，也可以不选分组，以访问账户可用的全部模型。

• 按需设置有效期、累计消费上限和模型价格保护；所有密钥共享账户余额。

• 配置时粘贴完整值。列表中的 sk-•••••• 是脱敏显示，不能直接使用。

图 1：点击右上角「创建密钥」，创建后使用该行的「复制」。截图中的名称、余额和用量仅作界面示意。

1.2 选择文本模型并复制模型 ID

打开 模型广场，选择「文字模型」分组，或切换到「文本」类型，查看当前可用模型、价格和状态。点击模型卡片中的「复制」，取得完整模型 ID。

例如，截图使用 gpt-6-astra。实际配置时以模型广场当前列出的 ID 为准，保留完整拼写、大小写和连字符，不自行添加前缀或版本后缀。

图 2：箭头指向的是「模型 ID」复制按钮。原图标注的“完整域名”应理解为“完整模型 ID”；接口地址在下一节单独填写。

找不到文字模型时，先检查筛选条件。模型广场默认的「全部」类型在普通分组下隐藏文本模型；主动选择「文字模型」分组或「文本」类型即可查看。模型可见并不代表当前 API Key 有权限调用它。

1.3 确认账户余额与模型权限

在 积分充值 查看余额并按需充值。密钥被禁用、已过期、达到消费上限或绑定了不包含目标模型的分组时，都无法正常调用。详细规则见 API Key 与权限。

2. 在 WorkBuddy 中使用本站文本模型

2.1 打开自定义模型设置

1. 打开 WorkBuddy，点击左下角头像，进入「设置」。

2. 在设置中选择「模型」。

3. 点击「添加模型」，供应商选择「自定义 / Custom」。已有配置可以点击编辑图标修改。

图 3：按图中 1 → 2 → 3 的顺序进入添加模型页面。

2.2 填写接口地址、API Key 和模型名称

可复制的接口地址：

https://y.junlistudio.com/v1/chat/completions

图 4：将图中的示例域名替换为上方本站地址。按照本文配置时，还需勾选「自定义协议」；原截图中该项尚未勾选。

本文采用“完整地址 + 开启自定义协议”的配置方式。不要把网站首页、文档链接或只有 /v1 的基础地址填进这个配置，也不要重复拼接 /chat/completions。

2.3 按模型能力设置高级配置

本站文本模型统一支持 /v1/chat/completions。不同模型的图片输入、工具调用、思考参数与上下文长度仍有差异，具体参见 文本对话与原生协议 和模型详情。

2.4 测试连接、保存并选中模型

1. 填写完成后点击「测试连接」。如果失败，按第 6 节检查接口地址、密钥、模型权限和余额。

2. 点击「保存」。

3. 回到对话页，在模型选择器的「自定义模型」中选中刚添加的模型。

4. 新建一个任务，发送一条简短消息，确认实际对话也能正常返回。

可使用下面的测试消息：

请只回复“连接成功”，不要调用工具。

需要文件处理或多步任务时，再用一项简单操作验证工具能力，例如：

请在我选定的工作目录中创建一个 workbuddy-test.txt 文件，写入“工具调用测试成功”，然后告诉我保存位置。

测试连接只说明该次检测通过；实际任务还可能涉及工具、图片输入或更长上下文，需要分别确认。测试及后续对话一旦发起模型调用，就可能产生本站费用。

2.5 添加或切换其他文本模型

重复「添加模型」流程，为每个模型填写对应的完整 ID。同一把 API Key 可以用于其权限范围内的多个模型。切换后先发一条简短消息验证；只有在对话中选中了本站自定义模型，相关文本请求才会使用这份配置。

3. 通过 WorkBuddy 生成和编辑图片

3.1 先准备图片调用工具

文本模型负责理解需求、组织提示词和调用工具。生成图片还需要一个能向本站图片 API 发起请求的本地工具或 WorkBuddy 技能；仅添加文本模型并开启「图片输入」不会自动接入生图功能。

如果尚未配置，可以让 WorkBuddy 阅读本站公开文档并创建调用工具。根据所用版本，可在「专家·技能·连接器 → 技能 → 添加技能 → 创建技能」中描述需求。下面的说明也可作为任务需求交给 WorkBuddy，由其在你选定的目录中实现并说明安装步骤。

请为我创建一个调用 Junli Studio 图片 API 的本地工具或 WorkBuddy 技能。

先阅读以下文档，再根据文档实现，不要猜测接口参数：
https://y.junlistudio.com/docs/images
https://y.junlistudio.com/docs/image-edit
https://y.junlistudio.com/docs/image-tasks
https://y.junlistudio.com/docs/image-results

要求：
1. API 基础地址使用 https://y.junlistudio.com/v1。
2. 密钥从本机环境变量 JUNLI_API_KEY 读取；请指导我在本机配置，不要让我把密钥发进聊天，也不要把密钥写入源码、技能正文或输出日志。
3. 先查询 /v1/models，确认模型 ID、密钥权限和支持的尺寸等参数。
4. 支持按文档提交文生图；参考图编辑按目标模型与对应文档实现。
5. 如果使用异步任务，保存任务 ID，持续查询至完成或失败，不能把“已提交”当成“生成成功”。
6. 成功后下载实际图片到我指定的目录，返回文件路径；失败时保留接口的具体错误说明。下载失败时先尝试重新下载已有结果，不重复提交生成。
7. 首次只完成工具创建和配置检查，列出一次生成需要的模型与参数，等我确认后再进行付费测试。

这里的 JUNLI_API_KEY 是供新建工具读取的本机环境变量名，并非 WorkBuddy 模型设置中的额外字段。工具读取的密钥需要包含图片模型权限；仅绑定「文字模型」的密钥不能直接用来生图。完成环境配置后，应确认 WorkBuddy 启动的工具进程能够读取该变量。

3.2 发起一次图片任务

工具安装并启用后，可以这样描述需求，将占位内容换成你选定的模型与目录：

请使用刚配置的 Junli Studio 图片工具，生成一张极简风格咖啡店宣传图。
模型：<从本站模型广场复制的图片模型 ID>
画面：暖色自然光、木质桌面、一杯拿铁，画面右侧留白，不添加文字。
比例：1:1；分辨率请选择该模型支持的一档。
生成前先列出最终模型、参数和当前价格；我确认后生成 1 张，下载到 <我的输出目录>。

需要修改已有图片时，提供参考图的本地路径或由工具支持的上传方式，并描述“保留什么、修改什么”。本地路径应由工具读取并转换成接口接受的文件或图像数据，不能直接当成服务器能访问的图片 URL。

3.3 选择正确的图片接口

MidJourney 的任务格式与普通图片接口不同。请在模型广场选择「MidJourney」分组查看对应模型，并让工具按 MJ 文档实现。

4. 通过 WorkBuddy 生成视频

4.1 配置提交、查询和下载流程

视频采用异步任务。WorkBuddy 的调用工具需要保存任务 ID，查询到完成后再下载；收到任务 ID 或 HTTP 200 都不代表视频已经生成成功。

可将下面的说明交给 WorkBuddy，为现有工具增加视频能力：

请为本地 Junli Studio 调用工具增加视频功能。
先阅读：
https://y.junlistudio.com/docs/video
https://y.junlistudio.com/docs/video-results

基础地址为 https://y.junlistudio.com/v1，密钥继续从本机环境变量 JUNLI_API_KEY 读取。
请按文档实现：
1. 查询可用视频模型，核对该模型支持的分辨率、时长、比例及参考素材要求。
2. 使用 POST /v1/videos 提交任务，并立即记录返回的任务 ID。
3. 使用 GET /v1/videos/{id} 查询状态；等待期间适度间隔查询，不重新提交同一任务。
4. 完成后按文档下载结果；使用 /v1/videos/{id}/content 时，将响应作为视频二进制保存。
5. 如果任务失败，展示接口返回的具体原因；网络中断时先恢复已有任务的查询。
6. 返回最终视频文件路径与任务 ID。首次付费测试前先让我确认模型、时长、分辨率和费用。

4.2 提交创作需求

请使用 Junli Studio 视频工具制作一段咖啡产品短片。
模型：<从本站模型广场复制的视频模型 ID>
内容：镜头缓慢推近桌上的拿铁，杯口有轻微热气，暖色窗光，画面稳定。
从该模型支持的选项中，列出可用的时长、分辨率、画面比例及本次费用。
我确认后只提交 1 个任务，等待完成并下载到 <我的输出目录>。

图生视频还需要目标模型支持的参考图。不要把其他模型的时长、尺寸或素材限制直接套用过来。部分模型另有专用接口，应以模型详情及对应文档为准。

4.3 等待与取回结果

• queued：任务已排队，继续查询。

• in_progress：任务处理中，继续查询。

• completed：任务已完成，可以获取结果。

• failed：任务失败，查看返回的具体错误原因。

任务尚未完成时，内容下载接口可能返回 HTTP 409。若已生成成功但本地下载中断，优先用原任务 ID 或结果地址恢复下载。临时结果链接可能过期，完成后及时保存文件。

5. 查看费用和使用记录

一次 WorkBuddy 任务可能包含多轮文本调用和一次或多次图片、视频生成，最终费用需要合并查看。文本支持按实际 token 或按次计费；图片、视频按所选模型与参数计费，以本站当前价格和积分流水为准。

文本调用不进入生成日志，也不在生成日志中保存对话内容。本站积分流水单独保留 30 天。预留费用不等于最终费用；退款及中断请求的结算规则见 积分与计费。WorkBuddy 客户端自身的套餐与功能规则以其产品说明为准。

6. 常见问题与排查

测试连接失败或返回 404

先核对完整地址是否为 https://y.junlistudio.com/v1/chat/completions，并确认「自定义协议」已开启。检查是否多写了 /v1、重复了 /chat/completions，或误填了文档地址。地址正确后，再根据返回的错误文案确认模型 ID 与接口状态；不要把所有 404 都判断为密钥问题。

提示密钥无效、未授权或已过期

重新从本站 API 密钥页复制完整值，检查是否已禁用或过期。WorkBuddy 的 API Key 输入框只填写密钥，不填写 Authorization: 或 Bearer 。

提示无模型权限或 model_not_allowed

检查密钥绑定的模型分组是否包含目标模型。文字模型密钥不能访问组外图片、视频模型。分组为空或已删除时限制仍然生效，需要在密钥编辑页重新选择分组或取消限制。

提示余额、消费上限或价格保护问题

分别检查账户余额、该密钥累计消费上限和模型价格保护。price_limit_exceeded 表示当前模型价格超出了密钥设定的保护范围；先核对价格与保护项，再决定是否调整。提高 WorkBuddy 的输入或输出长度不会解除这些限制。

能聊天，但不能读写文件或调用工具

确认已在对话中选中本站自定义模型，并为支持工具调用的模型开启该选项。再检查 WorkBuddy 对当前目录及工具执行的权限。单纯的文本回复成功，不能证明完整的工具流程也已通过。

上传图片后报错，或模型看不到图片

确认该模型支持图片输入，且 WorkBuddy 中已开启对应选项。检查图片格式、数量、大小和提交方式是否符合当前模型要求。需要 Base64 Data URL 的模型，应由工具按文档转换，不能直接传本地文件路径。

返回 400 或提示某个参数不支持

保留接口返回的具体原因，逐项检查对应参数。可以先关闭额外的思考或格式选项，使用最简单的文本请求验证，再逐步启用能力。不要为排错同时改动接口地址、密钥和模型名称。

出现 429、服务暂不可用或网络中断

按错误提示与实时监控判断是否需要降低并发、稍后重试或更换可用模型。对已提交的图片、视频异步任务，先查询原任务；结果未知时连续重新提交可能产生多次生成与费用。

模型回复“已生成”，但没有实际图片或视频

核对是否调用了对应媒体接口，是否取得真实任务 ID、完成状态和下载文件。只有文字描述或提示词不算生成结果；要求工具返回实际文件路径，或按接口文档提供可用的结果地址。

7. 相关文档

• API Key 与权限：密钥、分组、有效期与价格保护。

• 文本对话与原生协议：文本请求、工具调用与流式返回。

• 生成图片 · 编辑图片 · 异步图片任务。

• 创建视频 · 视频任务与下载。

• 积分与计费 · 错误处理与重试。

• WorkBuddy 官方模型配置说明：客户端设置和自定义协议行为。

• WorkBuddy 官方技能说明：技能创建、导入与启用方式。