# WorkBuddy 接入

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

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th><p>你想完成的事</p></th><th><p>接入方式</p></th><th><p>从哪里开始</p></th></tr><tr><td><p>对话、写作、代码与任务规划</p></td><td><p>在 WorkBuddy 中添加本站文本模型</p></td><td><p>第 2 节</p></td></tr><tr><td><p>识别上传的图片</p></td><td><p>选用支持图片输入的文本模型，并开启对应能力</p></td><td><p>第 2 节的高级配置</p></td></tr><tr><td><p>生成或编辑图片</p></td><td><p>让 WorkBuddy 通过本地工具或技能调用本站图片 API</p></td><td><p>第 3 节</p></td></tr><tr><td><p>生成视频</p></td><td><p>让 WorkBuddy 提交视频任务、查询状态并下载结果</p></td><td><p>第 4 节</p></td></tr></tbody></table>

<a id="1-接入前的准备"></a>

## 1\. 接入前的准备

<a id="1-1-创建一把-workbuddy-专用密钥"></a>

### 1.1 创建一把 WorkBuddy 专用密钥

登录本站，进入 [API 密钥](/api-keys)，点击「创建密钥」，名称可填写 `WorkBuddy`，然后复制完整密钥。

-   只使用文本模型时，可将密钥绑定到「文字模型」分组。
    
-   还要调用图片或视频模型时，需要使用有相应模型权限的密钥。可以分别创建密钥，也可以不选分组，以访问账户可用的全部模型。
    
-   按需设置有效期、累计消费上限和模型价格保护；所有密钥共享账户余额。
    
-   配置时粘贴完整值。列表中的 `sk-••••••` 是脱敏显示，不能直接使用。
    

![在本站 API 密钥页面创建并复制 WorkBuddy 专用密钥](/admin/api/docs/wiki/assets/8dfe17e4-5801-4f88-942e-2a0c65bf3d89)

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

<a id="1-2-选择文本模型并复制模型-id"></a>

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

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

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

![在模型广场选择文字模型分组并复制完整模型 ID](/admin/api/docs/wiki/assets/0b9ecf2e-f516-4342-a111-ad2179a888f6)

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

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

<a id="1-3-确认账户余额与模型权限"></a>

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

在 [积分充值](/recharge) 查看余额并按需充值。密钥被禁用、已过期、达到消费上限或绑定了不包含目标模型的分组时，都无法正常调用。详细规则见 [API Key 与权限](https://y.junlistudio.com/docs.md?page=api-keys)。

<a id="2-在-workbuddy-中使用本站文本模型"></a>

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

<a id="2-1-打开自定义模型设置"></a>

### 2.1 打开自定义模型设置

1.  打开 WorkBuddy，点击左下角头像，进入「设置」。
    
2.  在设置中选择「模型」。
    
3.  点击「添加模型」，供应商选择「自定义 / Custom」。已有配置可以点击编辑图标修改。
    

![WorkBuddy 设置中的模型入口与添加模型按钮](/admin/api/docs/wiki/assets/b06096cf-cc55-4618-aafb-41769d5d777a)

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

<a id="2-2-填写接口地址-api-key-和模型名称"></a>

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

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th><p>配置项</p></th><th><p>填写内容</p></th><th><p>说明</p></th></tr><tr><td><p>供应商</p></td><td><p>自定义 / Custom</p></td><td><p>使用 OpenAI 兼容协议接入</p></td></tr><tr><td><p>接口地址</p></td><td><p><code>https://y.junlistudio.com/v1/chat/completions</code></p></td><td><p>完整文本对话接口地址</p></td></tr><tr><td><p>API Key</p></td><td><p>在本站复制的完整密钥</p></td><td><p>直接粘贴密钥，不添加 <code>Bearer </code>前缀</p></td></tr><tr><td><p>模型名称</p></td><td><p>从模型广场复制的完整模型 ID</p></td><td><p>例如截图中的 <code>gpt-6-astra</code></p></td></tr><tr><td><p>自定义协议</p></td><td><p>开启</p></td><td><p>让 WorkBuddy 直接使用已填写的完整地址</p></td></tr></tbody></table>

可复制的接口地址：

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

![WorkBuddy 自定义模型的接口地址、API Key、模型名称与高级配置](/admin/api/docs/wiki/assets/59af353b-5cf5-48c5-886d-14a471aa4c5c)

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

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

<a id="2-3-按模型能力设置高级配置"></a>

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

<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th><p>选项</p></th><th><p>如何设置</p></th></tr><tr><td><p>工具调用</p></td><td><p>让 WorkBuddy 读写文件、执行工具或完成多步任务时，需要选择支持工具调用的模型并开启该项。只勾选开关不会让模型获得原本不支持的能力。</p></td></tr><tr><td><p>图片输入</p></td><td><p>需要识别截图或照片时，选择支持图片输入的模型并开启。它表示“看图”，不等于图片生成。</p></td></tr><tr><td><p>思考模式</p></td><td><p>初次接入可先关闭，基本对话通过后再按所选模型支持情况开启。不要对所有模型统一勾选。</p></td></tr><tr><td><p>自定义协议</p></td><td><p>按本文使用完整接口地址时开启。</p></td></tr><tr><td><p>输入 / 输出</p></td><td><p>初次接入可留空，使用默认值；需要调整时，以模型支持的上下文和输出长度为准。</p></td></tr></tbody></table>

本站文本模型统一支持 `/v1/chat/completions`。不同模型的图片输入、工具调用、思考参数与上下文长度仍有差异，具体参见 [文本对话与原生协议](https://y.junlistudio.com/docs.md?page=text) 和模型详情。

<a id="2-4-测试连接-保存并选中模型"></a>

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

1.  填写完成后点击「测试连接」。如果失败，按第 6 节检查接口地址、密钥、模型权限和余额。
    
2.  点击「保存」。
    
3.  回到对话页，在模型选择器的「自定义模型」中选中刚添加的模型。
    
4.  新建一个任务，发送一条简短消息，确认实际对话也能正常返回。
    

可使用下面的测试消息：

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

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

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

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

<a id="2-5-添加或切换其他文本模型"></a>

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

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

<a id="3-通过-workbuddy-生成和编辑图片"></a>

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

<a id="3-1-先准备图片调用工具"></a>

### 3.1 先准备图片调用工具

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

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

```text
请为我创建一个调用 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 启动的工具进程能够读取该变量。

<a id="3-2-发起一次图片任务"></a>

### 3.2 发起一次图片任务

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

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

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

<a id="3-3-选择正确的图片接口"></a>

### 3.3 选择正确的图片接口

<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th><p>需求</p></th><th><p>本站文档</p></th></tr><tr><td><p>普通文生图</p></td><td><p><a target="_blank" rel="noopener noreferrer" href="https://y.junlistudio.com/docs.md?page=images">生成图片</a>：<code>POST /v1/images/generations</code></p></td></tr><tr><td><p>参考图编辑</p></td><td><p><a target="_blank" rel="noopener noreferrer" href="https://y.junlistudio.com/docs.md?page=image-edit">编辑图片</a>：按模型支持的上传方式提交</p></td></tr><tr><td><p>较长时间的图片任务</p></td><td><p><a target="_blank" rel="noopener noreferrer" href="https://y.junlistudio.com/docs.md?page=image-tasks">异步图片任务</a>：<code>POST /v1/responses</code>，按文档设置后台任务并查询结果</p></td></tr><tr><td><p>获取和保存图片</p></td><td><p><a target="_blank" rel="noopener noreferrer" href="https://y.junlistudio.com/docs.md?page=image-results">图片结果与下载</a></p></td></tr><tr><td><p>MidJourney 生成、放大或变体</p></td><td><p><a target="_blank" rel="noopener noreferrer" href="https://y.junlistudio.com/docs.md?page=midjourney">MJ 接入概览</a>：使用 MJ 专用任务接口</p></td></tr></tbody></table>

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

<a id="4-通过-workbuddy-生成视频"></a>

## 4\. 通过 WorkBuddy 生成视频

<a id="4-1-配置提交-查询和下载流程"></a>

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

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

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

```text
请为本地 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。首次付费测试前先让我确认模型、时长、分辨率和费用。
```

<a id="4-2-提交创作需求"></a>

### 4.2 提交创作需求

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

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

<a id="4-3-等待与取回结果"></a>

### 4.3 等待与取回结果

-   `queued`：任务已排队，继续查询。
    
-   `in_progress`：任务处理中，继续查询。
    
-   `completed`：任务已完成，可以获取结果。
    
-   `failed`：任务失败，查看返回的具体错误原因。
    

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

<a id="5-查看费用和使用记录"></a>

## 5\. 查看费用和使用记录

<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th><p>使用场景</p></th><th><p>在本站如何核对</p></th></tr><tr><td><p>文本对话、工具规划、多轮任务</p></td><td><p>在 <a target="_blank" rel="noopener noreferrer" href="/credit-usage">积分流水</a> 按 WorkBuddy 密钥筛选，查看模型、用量和费用</p></td></tr><tr><td><p>图片或视频生成</p></td><td><p>查看 <a target="_blank" rel="noopener noreferrer" href="/mylogs">生成日志</a> 中的任务与错误，并在积分流水核对扣费、退款</p></td></tr><tr><td><p>模型当前价格与可用状态</p></td><td><p>查看 <a target="_blank" rel="noopener noreferrer" href="/model-square">模型广场</a> 和 <a target="_blank" rel="noopener noreferrer" href="/status">实时监控</a></p></td></tr></tbody></table>

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

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

<a id="6-常见问题与排查"></a>

## 6\. 常见问题与排查

<a id="测试连接失败或返回-404"></a>

### 测试连接失败或返回 404

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

<a id="提示密钥无效-未授权或已过期"></a>

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

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

<a id="提示无模型权限或-model_not_allowed"></a>

### 提示无模型权限或 `model_not_allowed`

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

<a id="提示余额-消费上限或价格保护问题"></a>

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

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

<a id="能聊天-但不能读写文件或调用工具"></a>

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

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

<a id="上传图片后报错-或模型看不到图片"></a>

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

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

<a id="返回-400-或提示某个参数不支持"></a>

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

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

<a id="出现-429-服务暂不可用或网络中断"></a>

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

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

<a id="模型回复-已生成-但没有实际图片或视频"></a>

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

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

<a id="7-相关文档"></a>

## 7\. 相关文档

-   [API Key 与权限](https://y.junlistudio.com/docs.md?page=api-keys)：密钥、分组、有效期与价格保护。
    
-   [文本对话与原生协议](https://y.junlistudio.com/docs.md?page=text)：文本请求、工具调用与流式返回。
    
-   [生成图片](https://y.junlistudio.com/docs.md?page=images) · [编辑图片](https://y.junlistudio.com/docs.md?page=image-edit) · [异步图片任务](https://y.junlistudio.com/docs.md?page=image-tasks)。
    
-   [创建视频](https://y.junlistudio.com/docs.md?page=video) · [视频任务与下载](https://y.junlistudio.com/docs.md?page=video-results)。
    
-   [积分与计费](https://y.junlistudio.com/docs.md?page=billing) · [错误处理与重试](https://y.junlistudio.com/docs.md?page=errors)。
    
-   [WorkBuddy 官方模型配置说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model)：客户端设置和自定义协议行为。
    
-   [WorkBuddy 官方技能说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market)：技能创建、导入与启用方式。