ComfyUI Custom API
更新时间:2024-11-04
ComfyUI Custom API 介绍
ComfyUI 是一款强依赖交互界面的 AIGC 应用,开发者很难通过其原始 API 进行二次开发。在此背景下我们提供了一套自定义的 ComfyUI 生图接口:接口封装了和 ComfyUI 服务交互的所有流程,仅一次调用即可获得生图结果;接口入参被简化的同时也保留了其灵活性,客户端代码的编写将格外容易。
根据使用场景将 API 区分为:
- ComfyUI Custom API:基础生图接口。
- OpenAI Format API:OpenAI 格式接口,可适配 OpenAI Python SDK、OpenAI JavaScript SDK。
ComfyUI 配置初始化
在调用 ComfyUI Custom API 之前需要做一些准备工作。
保存工作流
- 在 ComfyUI 应用主页启动一个实例,启动成功后点击『进入ComfyUI』。
- 在 ComfyUI 页面编辑好工作流后,点击左上角的保存按钮。保存之前,确保当前页面的工作流可以正常运行生图任务。
- 弹窗中输入工作流名称,默认值为 default。
- 保存工作流后,会在 my_workflows 目录生成三个文件(以名为 default 的工作流为例):
- default.json:工作流原始文件。无需手动修改。
- default_api.json:该文件中的信息与开发者模式下导出的 API Format 信息一致,是 ComfyUI 原始生图接口的入参。无需手动修改。
- default_api_mapping.json:字段映射表,作用是为工作流节点的具体字段动态赋值。比如在映射表中建立映射 mywidth→25.inputs.width,当请求生图接口时传入 mywidth=1024,工作流中 25 号节点的 width 就会被动态设置为 1024。节点信息如 25.inputs.width 可在 default_api.json 文件中查找。
左图请求传入 mywidth=1024,右图节点的 width 在生图过程中会被动态赋值为 1024
编辑字段映射表
- 在实例列表页面,点击『进入文件管理器』。
- 进入 my_workflows 目录,打开 default_api_mapping.json 文件。
- 修改 default_api_mapping.json 文件的内容,修改完成后保存。可参考以下代码块中的注释进行修改
{
"custom": { // custom 对象作用于 ComfyUI Custom API
"inputs": [ // inputs 列表定义入参映射
{
"from": "prompt", // from 指定了入参字段
"to": "15.inputs.prompt" // to 指定了目标节点的具体字段。节点信息可从 default_api.json 文件中查询
},
{
"from": "image", // 如果工作流要求上传图片,image 字段必须配置
"to": "29.inputs.image" // 指定图片上传节点
},
{
"from": "seed", // 如果希望触发随机种子效果,seed 必须配置
"to": "25.inputs.seed"
}
],
"outputs": [ // outputs 列表定义出参映射。如果工作流中有多个图片输出节点,可以配置多个 from-to 对象
{
"from": "5.inputs.images", // from 指定了图片输出节点。节点信息可从 default_api.json 文件中查询
"to": "image" // 图片输出节点的图片数据(生图结果)将赋值给 to 定义的出参字段
}
]
},
"openai": { // openai 对象作用于 OpenAI Format API
"inputs": [
{
"from": "prompt", // prompt 字段名不可修改
"to": "15.inputs.prompt"
},
{
"from": "size_x", // size_x 字段名不可修改
"to": "25.inputs.width"
},
{
"from": "size_y", // size_y 字段名不可修改
"to": "25.inputs.height"
},
{
"from": "image", // 如果调用 OpenAI edits 接口,image 必须配置
"to": "29.inputs.image"
},
{
"from": "seed", // 如果希望触发随机种子效果,seed 必须配置
"to": "25.inputs.seed"
}
],
"outputs": [
{
"from": "5.inputs.images",
"to": "url" // 此处 url 为占位符。修改该值不会产生任何效果
}
]
}
}
API 文档
获取必要信息
获取 Access Token:访问个人中心获取
获取 Host:点击『进入ComfyUI』,从弹出网页的地址栏中获取
ComfyUI Custom API
基础生图 API
请求地址:https://aigcapp-{appcode}.aistudio-app.com/api/v1/prompt
请求方式:POST
请求头:
名称 | 值 |
---|---|
Content-Type | application/json |
Authorization | Bearer {Access Token} |
请求 Body:
字段 | 类型 | 必填 | 填写说明 | 描述 |
---|---|---|---|---|
workflow_api | object | 否 | workflow_api 字段与 workflow 字段填写二选一 | 支持将开发者模式下导出的 API Format json 信息直接传入 workflow_api 字段 |
workflow | string | 否,默认值 default | 如果 workflow_api 有值则 workflow 不生效 | 声明工作流名称(保存工作流时输入的名称) |
inputs | object | 否 | 如果 workflow_api 有值则 inputs 不生效 | {"key1": "value1", "key2": "value2"} 1. key 对应 default_api_mapping.json 文件中 custom.inputs.from 值;value 则将被赋值给 custom.inputs.to 声明的工作流节点 2. key 也可以直接设置为工作流节点,比如 15.inputs.prompt 3. key 为 image 时,value 可以是图片 url、图片 b64、input 目录中的图片名 |
batch_count | integer | 否,默认值 1 | 取值范围 1~10 | 声明批次数量,即一次请求执行多次生图任务 |
response_format | string | 否,默认值 url | 取值范围 url、b64_json | 声明以 url 或 b64 的方式返回图片 |
响应 Body
名称 | 类型 | 说明 |
---|---|---|
logId | string | 请求事务 id |
errorCode | integer | 错误码 |
errorMsg | string | 错误信息 |
result | list |
OpenAI Format API
文生图 API
请求地址:https://aigcapp-{appcode}.aistudio-app.com/api/v1/images/generations
请求方式:POST
请求头:
名称 | 值 |
---|---|
Content-Type | application/json |
Authorization | Bearer {Access Token} |
请求 Body:
字段 | 类型 | 必填 | 填写说明 | 描述 |
---|---|---|---|---|
prompt | string | 是 | 提示词 | |
model | string | 否,默认值 default | 声明工作流名称(保存工作流时输入的名称) | |
n | integer | 否,默认值 1 | 取值范围 1~10 | 声明批次数量,即一次请求执行多次生图任务 |
response_format | string | 否,默认值 url | 取值范围 url、b64_json | 声明以 url 或 b64 的方式返回图片 |
size | string | 否,默认值 1024x1024 | 取值范围 256x256, 512x512, 1024x1024, 1792x1024, 1024x1792 |
声明生成的图片大小 |
响应 Body
名称 | 类型 | 说明 |
---|---|---|
created | integer | 生图时间戳,单位秒 |
data | list |
图生图 API
请求地址:https://aigcapp-{appcode}.aistudio-app.com/api/v1/images/edits
请求方式:POST
请求头:
名称 | 值 |
---|---|
Content-Type | multipart/form-data |
Authorization | Bearer {Access Token} |
请求表单信息:
字段 | 类型 | 必填 | 填写说明 | 描述 |
---|---|---|---|---|
image | file | 是 | 图片文件 | |
prompt | text | 是 | 提示词 | |
model | text | 否,默认值 default | 声明工作流名称(保存工作流时输入的名称) | |
n | text | 否,默认值 1 | 取值范围 1~10 | 声明批次数量,即一次请求执行多次生图任务 |
response_format | text | 否,默认值 url | 取值范围 url、b64_json | 声明以 url 或 b64 的方式返回图片 |
size | text | 否,默认值 1024x1024 | 取值范围 256x256, 512x512, 1024x1024, 1792x1024, 1024x1792 |
声明生成的图片大小 |
响应 Body
名称 | 类型 | 说明 |
---|---|---|
created | integer | 生图时间戳,单位秒 |
data | list |
错误码
错误码 | 错误信息 | 说明及排查建议 |
---|---|---|
6 | 令牌不匹配 | 请使用正确的 Access Token |
18 | 请求频率限制 | 单位时间内减少调用次数 |
40401 | 令牌错误或缺失 | 请使用正确的 Access Token |
40509 | 服务已停止 | 请重启服务 |
40701 | 获取工作流文件错误 | 请检查 my_workflows 目录中的映射文件是否配置正确 或检查入参指定的工作流名称是否正确 |
40702 | 上传图片错误 | 请检查传入的图片链接是否有效 |
40703 | inputs 中包含无效字段 | 请检查 inputs 中的字段是否能正确映射到工作流 或确保 inputs 字段对应的值非空 |
40705 | ComfyUI 接口报错 | 返回 ComfyUI 接口的原始报错,方便排查问题 |
40707 | 生成图片不合规 | 请修正传入的 prompt 或图片后重新生成 |
50001 | 传入内容不合规 | 请传入合规的 prompt 或图片 |
336000 | 服务内部错误 | |
336003 | 请求参数校验失败 | 根据返回的 errorMsg 对参数进行修正 |
336005 | 输入的 Host 不正确 | 请确保输入的 Host 正确,且对应的服务运行正常 |