API 文档

概览

Base URL：https://aihuanjie.com/api/v1

所有接口都需要通过用户设置页面生成一把 API 密钥，随每个请求发送：

X-Api-Key: {你的密钥}

请用这个头，不要用 Authorization: Bearer。本站所在主机的反向代理会把标准的 Authorization 请求头整个过滤掉，请求到达服务端时那个头已经不存在了——用它的话，无论密钥对不对都只会拿到 401 Unauthenticated，而且看不出任何跟请求头有关的线索。

服务端仍然同时接受 Authorization: Bearer {你的密钥}，那是为了以后换到不受这个限制的主机时不用改代码；在今天的部署下它不会生效。

密钥所属账号必须已经完成邮箱验证。没验证的账号既建不了密钥，也调不通任何接口——所有接口一律返回 403，正文是 {"message": "这个账号的邮箱还没有验证，暂时不能使用 API。请登录网站完成邮箱验证后再试。"}。

必须带的请求头

Header	值	说明
`X-Api-Key`	`{密钥}`（不带 `Bearer` 前缀）	必需。缺失或无效返回 401
`Authorization`	`Bearer {密钥}`	服务端认它，但本站主机的反代会把这个头滤掉，实际收不到——请改用上面那个
`Content-Type`	`application/json`	请求体是 JSON 时必需
`Accept`	`application/json`	必需——不带这个头，请求参数校验失败时可能不会返回你期望的 JSON 错误格式（框架层面的内容协商行为），务必带上

响应格式约定

成功响应统一包在 data 字段里：

{ "data": { ... } }

失败响应统一是：

{ "message": "出错原因", "errors": { "字段名": ["具体错误"] } }

errors 字段只在请求参数校验失败（422）时才有，其它错误只有 message。

限流

按密钥限流，分两档：真正会触发生成的接口（预估生成耗时、提交生成任务）是 600 次/分钟；查询生成任务状态这个接口是 3000 次/分钟（轮询用，成本低所以额度更宽松）。这两个数字都刻意设得很高——正常使用（哪怕你的网站背后有很多用户在同时用同一把密钥）基本不会碰到，只是留一道防线，防止密钥泄露被恶意刷、或者代码出 bug 死循环调用。超过限制返回 429，具体每个接口的限流档位见各自的错误响应表格。

密钥的权限在生成密钥时设置，具体去用户设置页面配置。

POST https://aihuanjie.com/api/v1/estimates 预估生成耗时

传一张图片和一个工作流 id，返回这个工作流在这次输入图片尺寸下大概要跑多久、以及这次生成要花多少幻晶（不会真正提交生成任务，纯预估，不扣任何幻晶）。预估基于该工作流历史上真实完成的生成记录校准出来，第一次使用某个工作流、还没有历史数据时无法给出精确预估。

预估假设走的是常驻服务器这条路径；实际提交生成任务时如果常驻服务器繁忙会自动溢出到 Serverless，届时可能因为冷启动而更慢——这个接口给出的是正常情况下的参考值，不是精确保证。

price 里的币数与「提交生成任务」真正扣的是同一套计价，可以先查价再决定要不要提交。price.priceable 是 false 时，这个工作流暂时无法定价，提交生成任务会返回 422。

API 调用只能用付费币（紫幻晶），免费币在这条路径上不可用——所以 price.currency 恒为 paid。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

请求体

字段	类型	必需	说明
`workflow_id`	integer	是	要跑的工作流 id，必须是已发布状态，草稿状态的工作流 id 会返回 404
`image`	string	是	图片内容，base64 编码。支持纯 base64 字符串，也支持带 data:image/png;base64,... 前缀的 data URI。解码后大小不能超过 20MB。

示例请求

curl -X POST "https://aihuanjie.com/api/v1/estimates" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": 12,
    "image": "iVBORw0KGgoAAAANSUhEUgAA...（省略，实际请求里放完整 base64）"
}'

示例响应（200）

{
    "data": {
        "workflow_id": 12,
        "image": {
            "width": 1024,
            "height": 1024,
            "megapixels": 1.048599999999999976552089719916693866252899169921875
        },
        "estimate": {
            "precision": "parametric",
            "estimated_seconds": 42.2999999999999971578290569595992565155029296875,
            "sample_size": 18,
            "expected_megapixels": 1.048599999999999976552089719916693866252899169921875,
            "megapixels_source": "submitted_image"
        },
        "price": {
            "priceable": true,
            "currency": "paid",
            "coins": 43,
            "by_batch_size": {
                "1": 43,
                "2": 82,
                "4": 155
            }
        }
    }
}

字段说明

字段	说明
`estimate.precision`	parametric——按历史数据校准出的"秒/百万像素"系数算出来的，相对精确；rough——历史数据不足以拆出这个系数，退化成历史耗时的粗略平均，跟这次图片大小无关；none——这个工作流还没有任何成功完成的历史记录，无法预估
`estimate.estimated_seconds`	预估耗时（秒）。precision 是 none 时为 null
`estimate.sample_size`	用了多少条历史记录计算出这个预估
`estimate.megapixels_source`	submitted_image——用的是你这次传的图片真实尺寸；historical_average——用的是历史平均尺寸；null——历史数据不够拆出系数，没用上像素信息（此时 precision 已经是 rough）
`price.priceable`	这个工作流现在能不能定价。false 时 coins 为 null，提交生成任务会返回 422
`price.coins`	出 1 张要花多少幻晶（付费币）。这就是提交生成任务时真正扣的数字
`price.by_batch_size`	各张数档位对应的币数。批量有固定开销摊薄，所以不是简单的整数倍；档位以这里列出的为准，传别的数字会返回 422（视频类工作流固定只有 1 段）

错误响应

状态码	触发条件	示例
401	未认证——没带 Authorization 头，或者密钥无效/已删除	`{"message":"Unauthenticated."}`
403	密钥没有 generate 权限	`{"message":"这把密钥没有\"提交生成任务\"权限。"}`
404	workflow_id 不存在，或者对应工作流还是草稿状态	`{"message":"工作流不存在，或者还没发布。"}`
422	workflow_id/image 缺失或类型不对	`{"message":"请求参数有误。","errors":{"image":["The image field is required."]}}`
422	image 不是合法的 base64 编码	`{"message":"image 字段不是合法的 base64 编码。"}`
422	解码后的图片超过大小上限	`{"message":"图片过大，超过 20MB 限制。"}`
422	解码后的内容不是合法的图片文件	`{"message":"image 字段不是合法的图片文件。"}`
429	超过限流（600 次/分钟，正常使用基本不会碰到，只在异常高频调用时触发）	`{"message":"Too Many Attempts."}`

POST https://aihuanjie.com/api/v1/generations 提交生成任务

提交一次真正的生成任务。推荐按**生态**寻址：传 ecosystem_id + mode，再带上你选的大模型、增强模型和参数值——用哪条工作流由我们自己找，你不用关心。参数名和取值范围来自「生态的参数表」接口。

两种寻址方式二选一：① ecosystem_id + mode（推荐，配合上面那四个目录接口用）；② workflow_id（老写法，仍然支持——有些工作流不挂在任何生态槽位上，只能这么调）。两个都不传返回 422。

大模型不放在 parameters 里，用顶层的 checkpoint_version_id（取值是「生态下的大模型」接口返回的 version_id）。传一个不属于这个生态的 version_id 会返回 422，不会被悄悄换成默认模型。

⚠️ 这个生态的工作流**有没有映射大模型槽**，看「生态的参数表」返回的 slots.checkpoint.mapped。为 false 时基底模型写死在工作流模板里，你传 checkpoint_version_id 也不会生效，而且不报错——界面上那个选择器该藏起来。

增强模型用顶层的 loras 数组，同样不放在 parameters 里。

这个接口只负责提交任务，不会等待生成完成——用返回的 job_id 调用下面的「查询生成任务」接口自行轮询。

这个接口会**真正扣费**：按下方「可用工作流」列表里那个工作流的价格扣**付费币（紫幻晶）**，免费币在 API 上不可用。余额不够时返回 402，不会欠费。想先知道要花多少，用上面的「预估生成耗时」接口查 price。

生成失败或超时会**全额退回**，成功才真正结算——扣费在提交那一刻先冻结，任务到终态时才落账。

同一个账号在站内和 API 上共用同一份并发额度（普通用户 1 个、会员 4 个）；额度占满时返回 429，等在跑的任务结束再提交。

提示词与图片参数都会先过内容审核，未通过时返回 422 且**不扣任何幻晶**。

出几张由 parameters 里那个张数参数决定（没传就是 1 张），账单严格按这个数字算；传一个不在允许档位里的数字会返回 422。

如果你在设置页给这把密钥设了「消费限额」，超出限额时返回 429（不是 402）——限额是按「最近 N 个整点小时」滑动计算的，统计的是提交时冻结的币数，生成失败退回的部分不回冲。

价钱只看工作流与张数，**不按参数动态计价**；作为对价，参数里的数值会被夹在这个工作流每个参数各自的取值范围内（下方「可用工作流」列表里标着的最小值/最大值），超出范围不报错，按边界值执行，字符串超长会被截断。

增强模型（LoRA）不放在 parameters 里，走顶层的 loras 数组——parameters 是一张扁平的「参数名 => 单个值」表，装不下变长列表。

这个接口没有单独的 image 字段——图片和文字/数字/开关这些参数走同一个入口：都放在 parameters 对象里，key 用这个工作流给这个参数起的名字（在下方「可用工作流」列表里能查到，类型标"图片"的那一行）。同一个工作流可能有 0 个、1 个、甚至多个图片参数，具体看它开放了哪些。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

请求体

字段	类型	必需	说明
`workflow_id`	integer	是	要跑的工作流 id（跟 ecosystem_id 二选一）。见页面最后的「按工作流直接调用」列表。这条路没有"选大模型"这件事——模型由工作流模板决定。
`ecosystem_id`	integer	否	要用哪个生态（跟 workflow_id 二选一，推荐用这个）。取值见「生态列表」接口。
`mode`	string	否	跟 ecosystem_id 一起传，例如 text_to_image。
`controlnet`	boolean	否	传 true 时走这个生态的 ControlNet 变体（另一条工作流，参数表不同）。只在「生态的参数表」里 supports_controlnet 为 true 时可用。
`checkpoint_version_id`	integer	否	用哪个基底模型，取值是「生态下的大模型」接口返回的 version_id。不传就用这个生态的默认模型。只在按 ecosystem_id 寻址时有效。
`loras`	array	否	要挂的增强模型（LoRA）列表，每项是 {"version_id": 版本id, "strength": 强度}。version_id 从「生态下的增强模型」接口拿（是 version_id 那一格，不是 id）。数组顺序就是叠加顺序。挂几个有上限——取值见「生态的参数表」里的 slots.enhancers.max，那是这条工作流自己的上限，不是全站的；超了返回 422。strength 选填，合法区间见 slots.enhancers.strength，超出区间不报错、会被夹到边界。挂了增强模型通常还要把它的触发词写进提示词里，否则多半不起作用——触发词也在那个接口里返回。
`parameters`	object	否	参数名 => 值，支持字符串/整数/数字/布尔值/图片（不支持数组/对象）。具体每个工作流开放哪些参数、类型是什么、是否必填，见下方「可用工作流」列表；传一个不存在的参数名，或者漏传某个必填参数，都会返回 422。类型是"图片"的参数，值必须是 base64 编码的图片内容（纯 base64 字符串或者带 data:image/...;base64, 前缀的 data URI 都可以），解码后大小上限 20MB。

示例请求

curl -X POST "https://aihuanjie.com/api/v1/generations" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "ecosystem_id": 1,
    "mode": "text_to_image",
    "checkpoint_version_id": 131155,
    "parameters": {
        "prompt_text": "a cat, masterpiece",
        "seed": 12345,
        "source_image": "iVBORw0KGgoAAAANSUhEUgAA...（省略，实际请求里放完整 base64，仅当参数表里有图片类型的参数时才需要传）"
    },
    "loras": [
        {
            "version_id": 2211,
            "strength": 0.8000000000000000444089209850062616169452667236328125
        }
    ]
}'

示例响应（200）

{
    "data": {
        "job_id": 88,
        "status": "pending",
        "execution_path": "persistent",
        "charged_coins": 43
    }
}

字段说明

字段	说明
`job_id`	这次生成任务的 id，用来调用「查询生成任务」接口
`status`	任务刚创建时的状态，通常是 pending（走常驻服务器）或 running（走 Serverless，已经提交出去了）
`execution_path`	persistent——走常驻服务器；serverless——常驻服务器繁忙，溢出到了 Serverless
`charged_coins`	这次冻结的幻晶数量（付费币）。任务成功后按这个数字结算，失败或超时全额退回

错误响应

状态码	触发条件	示例
401	未认证——没带 Authorization 头，或者密钥无效/已删除	`{"message":"Unauthenticated."}`
403	密钥没有 generate 权限	`{"message":"这把密钥没有\"提交生成任务\"权限。"}`
404	workflow_id 不存在或还没发布；或者 ecosystem_id 不存在；或者这个生态在该模式下没配工作流	`{"message":"这个生态在该模式下没有可用的工作流。"}`
422	checkpoint_version_id 不属于这个生态，或者那个版本当前不可用	`{"message":"这个大模型不属于该生态，或者当前不可用。"}`
422	workflow_id 缺失或类型不对，或者 parameters 里某个值是数组/对象	`{"message":"请求参数有误。","errors":{"workflow_id":["The workflow id field is required."]}}`
422	这个工作流暂时不可用（不应该发生在「可用工作流」列表里出现过的 id 上，如果遇到请联系我们）	`{"message":"这个工作流暂时不可用，请稍后再试或联系我们。"}`
422	参数处理失败——传了一个不存在的参数名、缺少某个必填参数、或者某个参数的值类型不对	`{"message":"参数替换失败。","errors":{"parameters":["未知参数：foo（这个工作流没有定义同名的参数映射）","缺少必填参数：prompt_text"]}}`
422	图片类型参数处理失败——不是合法的 base64/图片文件、或者超过大小上限	`{"message":"图片参数处理失败。","errors":{"parameters":["参数「source_image」：不是合法的图片文件。"]}}`
422	张数不在允许的档位里	`{"message":"张数只能是 1 / 2 / 4 之一。"}`
422	提示词或图片没通过内容审核（不扣任何幻晶）	`{"message":"内容审核未通过：未成年人相关内容。请修改后重试。"}`
402	付费币（紫幻晶）不足。不允许欠费——先充值或兑换卡密，再重试	`{"message":"紫幻晶不足：本次需要 43 枚，当前可用 12 枚。"}`
403	账号当前不能提交生成任务（邮箱未验证，或者账号处于封禁 / 禁生成状态）	`{"message":"这个账号当前不能提交生成任务（邮箱未验证，或者账号处于封禁 / 禁生成状态）。"}`
429	并发额度已占满（站内与 API 共用同一份额度），等在跑的任务结束再提交	`{"message":"你还有 1 个任务正在进行，同时最多只能跑 1 个。等它完成后再提交。","errors":{"concurrency":{"allowed":false,"tier":"default","limit":1,"in_flight":1,"remaining":0}}}`
429	短时间内多次被内容审核拒绝，已进入暂停期	`{"message":"你在 1 小时内被拒绝多次，已暂停生成，请 47 分钟后再试。"}`
429	这把密钥自己设的用量配额已用满（在设置页给密钥设过「消费限额」时才可能出现）。充值没用，要么等窗口过去，要么在设置页调高/取消这把密钥的配额	`{"message":"这把密钥的用量配额已用满：最近 24 小时内上限 100 枚紫幻晶，已用 100 枚。等窗口过去，或在设置页调整这把密钥的配额。","errors":{"quota":{"enabled":true,"limit":100,"window_hours":24,"used":100,"requested":43,"remaining":0,"allowed":false}}}`
500	服务端故障（例如图片上传到 ComfyUI 失败）。这类错误不代表请求有问题，隔几秒重试即可；不会扣任何幻晶	`{"message":"Server Error"}`
429	超过限流（600 次/分钟，正常使用基本不会碰到，只在异常高频调用时触发）	`{"message":"Too Many Attempts."}`

GET https://aihuanjie.com/api/v1/generations/{job_id} 查询生成任务

查询一次生成任务的当前状态和结果图。只能查通过你自己这个账号（不区分具体是哪一把密钥）提交过的任务，查别人的任务 id 会返回 404。

目前只能轮询，没有 webhook 回调机制——建议每隔几秒查一次，直到 status 变成 completed 或 failed。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

示例请求

curl -X GET "https://aihuanjie.com/api/v1/generations/{job_id}" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json"

示例响应（200）

{
    "data": {
        "job_id": 88,
        "status": "completed",
        "execution_path": "persistent",
        "progress_percent": 100,
        "progress_message": null,
        "error_message": null,
        "charged_coins": 43,
        "outputs": [
            {
                "id": 201,
                "url": "https://cdn.example.com/civitai/generations/88/0.png",
                "title": null,
                "width": 1024,
                "height": 1024
            }
        ]
    }
}

字段说明

字段	说明
`status`	pending\|claimed\|running\|completed\|failed
`progress_percent`	0-100，粗粒度进度，不是每个节点的精确进度；不确定时为 null
`error_message`	status 是 failed 时的具体错误信息，其它状态下为 null
`charged_coins`	这次任务当初冻结/扣掉的幻晶数量（付费币）。任务失败或超时时这笔钱会全额退回，这个字段仍然显示当初按什么价扣的
`outputs`	结果图片列表，生成完成前是空数组

错误响应

状态码	触发条件	示例
401	未认证——没带 Authorization 头，或者密钥无效/已删除	`{"message":"Unauthenticated."}`
403	密钥没有 generate 权限	`{"message":"这把密钥没有\"提交生成任务\"权限。"}`
404	job_id 不存在，或者不是你自己账号提交的任务	`{"message":"生成任务不存在。"}`
429	超过限流（3000 次/分钟，比提交生成任务宽松得多，专门为轮询设计，正常使用基本不会碰到）	`{"message":"Too Many Attempts."}`

GET https://aihuanjie.com/api/v1/ecosystems 生态列表

列出站内全部生态，按母分类分组。生态决定这次生成用哪条工作流、能选哪些模型——它是所有其它目录接口的入口。

强烈建议带上 mode 参数。不带的话返回全部生态，其中有些并没有配你要的那个模式，调用方点进去只会拿到 404。

modes 里每个模式的布尔值表示"这个生态在这个模式下配好了已发布的工作流"——草稿状态的工作流不算配好，不会显示为 true。

这个列表不长（通常几十条），没有分页。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

查询参数

字段	类型	必需	说明
`mode`	string	否	只返回支持这个模式的生态。可选值见提交生成任务那一节的 mode；不认识的值返回 422（不会被静默忽略）。

示例请求

curl -X GET "https://aihuanjie.com/api/v1/ecosystems?mode=text_to_image" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json"

示例响应（200）

{
    "data": [
        {
            "id": 3,
            "name": "写实",
            "ecosystems": [
                {
                    "id": 12,
                    "name": "真人摄影",
                    "is_default": true,
                    "modes": {
                        "text_to_image": true,
                        "image_to_image": true,
                        "text_to_video": false
                    }
                }
            ]
        }
    ]
}

字段说明

字段	说明
`data[].id`	母分类 id，只用来分组显示
`data[].ecosystems[].id`	生态 id——下面三个接口都拿它当路径参数
`data[].ecosystems[].is_default`	站内默认选中的那个生态；没有特别偏好时可以照着选
`data[].ecosystems[].modes`	每个模式能不能做。按它置灰界面上的模式切换，别让用户选到一个必然 404 的组合

错误响应

状态码	触发条件	示例
401	未认证——没带 Authorization 头，或者密钥无效/已删除	`{"message":"Unauthenticated."}`
403	密钥没有 generate 权限	`{"message":"这把密钥没有权限。"}`
422	mode 不是可选值之一	`{"message":"不认识的 mode。"}`

GET https://aihuanjie.com/api/v1/ecosystems/{ecosystem_id}/parameters 生态的参数表

这个生态在某个模式下能调哪些参数：每个参数的键名、类型、默认值、取值范围和说明。提交生成任务时 parameters 那个对象的键，就是这里返回的 name。

mode 必填。不给就默认返回某一个模式的参数，是最糟的猜测——两个模式的参数表可以完全不同。

只返回面向用户的参数。运营在后台固定死的那些内部参数不在列表里，传了也不会生效。

min / max / step / max_length 这几个键只在真的设了限制时才出现。永远输出 null 会让人分不清"没有下限"和"下限是 0"——所以请用"键存不存在"来判断，不要用值是不是 null。

options 存在时表示这个参数只能从这几个值里选（下拉框），不存在就是自由输入。

数值参数超出 min/max 时**不报错**，服务端会夹到边界；字符串超过 max_length 会被截断。价钱只看工作流与张数，不按参数动态计价——所以把 steps 调到上限之外也不会更贵，只是不生效。

slots 那一段说的是「参数表以外的映射点各由哪个字段来填」：大模型用顶层的 checkpoint_version_id、增强模型用顶层的 loras，两者都不在 parameters 里。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

查询参数

字段	类型	必需	说明
`mode`	string	是	要看哪个模式的参数表，比如 text_to_image
`controlnet`	boolean	否	传 1 时返回这个生态的 ControlNet 变体——那是另一条工作流，workflow_id 和参数表都不一样（会多出参考图、处理器、强度这几个参数）。只在上面「生态列表」里 supports_controlnet 为 true 时才有；没配变体时返回 404。

示例请求

curl -X GET "https://aihuanjie.com/api/v1/ecosystems/12/parameters?mode=text_to_image" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json"

示例响应（200）

{
    "data": {
        "ecosystem_id": 12,
        "mode": "text_to_image",
        "workflow_id": 45,
        "workflow_name": "真人摄影 · 文生图",
        "supports_controlnet": true,
        "parameters": [
            {
                "name": "prompt",
                "label": "画什么",
                "type": "string",
                "role": "prompt",
                "control": "textarea",
                "required": true,
                "advanced": false,
                "sort_order": 0,
                "default": null,
                "description": null,
                "help_text": "用大白话描述就行，系统会自动改写成模型吃得下的提示词",
                "max_length": 500
            },
            {
                "name": "steps",
                "label": "步数",
                "type": "int",
                "role": "steps",
                "control": "slider",
                "required": false,
                "advanced": true,
                "sort_order": 2,
                "default": "8",
                "description": null,
                "help_text": "越大越慢",
                "min": 1,
                "max": 50,
                "step": 1
            }
        ]
    }
}

字段说明

字段	说明
`workflow_id`	这个生态+模式实际会跑的工作流 id。「预估生成耗时」那个接口要的就是它
`controlnet`	这份参数表是不是 ControlNet 变体的（跟请求里的 controlnet 参数对应）
`supports_controlnet`	这个组合配了 ControlNet 变体没有；false 时界面上那块应该整个藏起来。为 true 时用 ?controlnet=1 再请求一次，拿变体自己的 workflow_id 和参数表
`parameters[].name`	提交生成任务时 parameters 对象的键，就是它
`parameters[].type`	string / int / float / bool 等，决定你该传什么类型的值
`parameters[].role`	这个参数在工作流里扮演什么角色：prompt（正向提示词）、negative_prompt、seed、image_width、image_height、steps、cfg 等。参数的 name 是运营起的，按名字猜必然出错——要认出"哪个是提示词"请用这一格。普通参数没有角色，为 null
`parameters[].advanced`	true 表示站内把它收在"高级"里；不懂的话照着 default 传就行
`parameters[].default`	不传这个参数时用的值。为 null 表示没有默认值
`parameters[].options`	存在时表示只能从这几个值里选；不存在就是自由输入
`batch_sizes`	一次能出几张的全部合法取值。张数那个参数（role = batch_size）只能填这里面的数，填别的提交时返回 422。视频固定只能 1 段
`slots.checkpoint.mapped`	false 表示这条工作流的基底模型写死在模板里：传 checkpoint_version_id 也不会生效，而且不报错。为 false 时界面上的大模型选择器该整个藏起来
`slots.enhancers.mapped`	false 表示这条工作流挂不了增强模型
`slots.enhancers.max`	这条工作流最多能挂几个增强模型（不是全站上限）。超了提交时返回 422。双专家生态按每条主干各自算
`slots.enhancers.strength`	强度的合法区间。超出区间不报错，服务端会夹到边界——前端自己限住，用户才知道发生了什么

错误响应

状态码	触发条件	示例
403	密钥没有 generate 权限	`{"message":"这把密钥没有权限。"}`
404	生态不存在，或者这个生态在该模式下没有配已发布的工作流	`{"message":"这个生态在该模式下没有可用的工作流。"}`
422	没传 mode，或者 mode 不是可选值之一	`{"message":"缺少 mode 参数。"}`

GET https://aihuanjie.com/api/v1/ecosystems/{ecosystem_id}/checkpoints 生态下的大模型

这个生态背后的基底模型（Checkpoint）列表，带展示图、模型信息和中文介绍。用来告诉用户"这个生态是用什么模型出图的"。

⚠️ 目前**不能通过 API 指定用哪个基底模型**：每条工作流的基底模型是在工作流模板里定死的，提交接口没有接收它的字段。这个接口是**展示用**的——把模型名字、示例图、介绍显示给用户看，帮他挑生态，而不是挑模型。要换基底模型就换生态（或换 workflow_id）。

version_id 给的是这个模型在当前生态下最新的可用版本，用来跟站内对齐、做去重和跳转。它和「增强模型」那个接口里的 version_id 不是一回事——只有增强模型的 version_id 能填进提交接口的 loras 里。

images 给的是静态图地址，展示位是视频时给的是封面帧——可以直接塞进 <img>。取不到静帧的展示位会被跳过，所以这个数组可能比站内看到的短，每个模型最多 6 张。

列表跟站内用同一套可见规则：站内下架、没同步完、没有展示图的模型，在这里同样读不到。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

查询参数

字段	类型	必需	说明
`q`	string	否	按名称搜索，最长 100 字
`page`	integer	否	第几页，从 1 开始
`per_page`	integer	否	每页几条，1–100，默认 24

示例请求

curl -X GET "https://aihuanjie.com/api/v1/ecosystems/12/checkpoints?q=写实&per_page=24" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json"

示例响应（200）

{
    "data": [
        {
            "id": 771,
            "version_id": 1902,
            "name": "基底模型 · 幻界 · 澄澈晨光",
            "type": "Checkpoint",
            "base_model": "SDXL 1.0",
            "nsfw": false,
            "description": "偏写实的通用基底模型，人像和风景都能出。",
            "images": [
                "https://cdn.example.com/civitai/showcase/771-0.jpeg",
                "https://cdn.example.com/civitai/showcase/771-1.jpeg"
            ]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 24,
        "total": 37,
        "last_page": 2
    }
}

字段说明

字段	说明
`data[].id`	模型 id，用来做去重和跳转
`data[].version_id`	当前生态下最新可用版本的 id。⚠️ 基底模型不能通过 API 指定，这一格不填进提交接口的任何字段——能填进 loras 的是「增强模型」那个接口返回的 version_id
`data[].base_model`	底模架构（SDXL 1.0 / Flux.1 D 等）。同一个生态下通常是一致的
`data[].description`	中文介绍，内容是 Markdown（会出现 ## 标题、列表等），不是纯文本——直接当纯文本显示会看到字面的 ## 符号。还没翻译过的退回英文原文，都没有时为 null
`meta`	分页信息，跟 data 平级

错误响应

状态码	触发条件	示例
403	密钥没有 generate 权限	`{"message":"这把密钥没有权限。"}`
404	生态不存在	`{"message":"生态不存在。"}`
422	per_page 超出 1–100，或 q 超过 100 字	`{"message":"请求参数有误。"}`

GET https://aihuanjie.com/api/v1/ecosystems/{ecosystem_id}/enhancers 生态下的增强模型

这个生态下能挂的增强模型（LoRA 家族）列表。字段跟上面的大模型接口一样，另外多一列触发词。

提交生成任务时 loras[].version_id 要的同样是 version_id，不是 id。

trigger_words 是这个增强模型的触发词：word 是要写进提示词里的原文（通常是英文），zh 是中文意思，没翻译过时为 null。展示给用户看中文，真正提交时用 word。

大模型那个接口不会返回 trigger_words 这个键——大模型没有触发词这回事，给个空数组只会让人以为是没配。

需要的权限

密钥必须具备 generate（提交生成任务）权限，否则返回 403。

查询参数

字段	类型	必需	说明
`q`	string	否	按名称搜索，最长 100 字
`page`	integer	否	第几页，从 1 开始
`per_page`	integer	否	每页几条，1–100，默认 24

示例请求

curl -X GET "https://aihuanjie.com/api/v1/ecosystems/12/enhancers?per_page=24" \
  -H "X-Api-Key: {你的密钥}" \
  -H "Accept: application/json"

示例响应（200）

{
    "data": [
        {
            "id": 903,
            "version_id": 2211,
            "name": "增强模型 · 幻界 · 胶片颗粒",
            "type": "LORA",
            "base_model": "SDXL 1.0",
            "nsfw": false,
            "description": "给画面加上老胶片的颗粒感和偏色。",
            "images": [
                "https://cdn.example.com/civitai/showcase/903-0.jpeg"
            ],
            "trigger_words": [
                {
                    "word": "film grain",
                    "zh": "胶片颗粒"
                },
                {
                    "word": "analog photo",
                    "zh": null
                }
            ]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 24,
        "total": 8,
        "last_page": 1
    }
}

字段说明

字段	说明
`data[].version_id`	提交生成任务时 loras[].version_id 要的就是它
`data[].trigger_words[].word`	要写进提示词里的原文。不写触发词的话这个增强模型多半不起作用
`data[].trigger_words[].zh`	中文意思，用来展示给用户；还没翻译的为 null

错误响应

状态码	触发条件	示例
403	密钥没有 generate 权限	`{"message":"这把密钥没有权限。"}`
404	生态不存在	`{"message":"生态不存在。"}`
422	per_page 超出 1–100，或 q 超过 100 字	`{"message":"请求参数有误。"}`

按工作流直接调用（兼容）

下面这些是不走生态、直接按 workflow_id 调用时的参数参考。新接入不用看这一节——按生态调用时，参数表由「生态的参数表」接口给出。

这一节留着是因为有些工作流不挂在任何生态槽位上，只能这么调。

workflow_id: 3 幻界明舟图片修改

本工作流能够任意修改图片中人物的状态，动作，行为等等。也可以添加删除物品。

可用参数

参数名	类型	是否必填	说明
`image`	图片（base64，自动上传到 ComfyUI）	必填	—
`negative_prompt`	字符串	选填	负面图示词
`positive_prompt`	字符串	必填	正面提示词