MULIN API / DOCUMENTATION

从此处，接续灵感。

用一枚暮临 API Key，连接对话与图像生成。
从模型查询开始，再发出你的第一次请求。

OpenAI 兼容协议NovelAI 原生格式余烬计费

快速开始

登录控制台，在「API Key」中创建自己的密钥。为密钥配置可用额度和所需模型权限，并确认账户有足够余烬。

OpenAI 兼容 Base URLhttps://mulinapi.com/v1

请求鉴权Authorization: Bearer YOUR_MULIN_API_KEY

客户端选择「OpenAI 兼容」或「自定义 OpenAI」，填入以上 Base URL 和你的暮临密钥。如果客户端会自动追加 /v1，请只填 https://mulinapi.com，避免路径重复。

两种使用方式

应用或脚本使用自己的暮临 API Key；网页试炼场登录后直接使用本人余额，无需手动填写密钥。API Key 不是登录密码，也不是 NovelAI 官方密钥。请在服务端保管，不要写入公开的网页代码。

准备示例环境

下方 curl 示例适用于 Bash / zsh。先把占位内容替换为你的密钥；代码示例本身不会发起请求。

SHELL · 环境变量

export MULIN_API_KEY='YOUR_MULIN_API_KEY'

使用 Windows PowerShell 时，可调用 curl.exe，并按 PowerShell 的环境变量与引号语法调整命令。

接口一览
用途	方法	路径
可用模型	GET	`/v1/models`
对话 / 流式对话	POST	`/v1/chat/completions`
图像生成 · JSON	POST	`/v1/images/generations`
NovelAI 原生 · ZIP	POST	`/ai/generate-image`

查询可用模型

可用模型受当前接入情况、密钥分组和模型权限影响，以 /v1/models 的实际返回结果为准。查询模型不会执行推理。

CURL · 获取模型

curl --fail-with-body https://mulinapi.com/v1/models \
  -H "Authorization: Bearer $MULIN_API_KEY"

读取返回的 data[].id，把适合所需接口的模型 ID 原样传入 model。更多能力与价格见模型目录。

对话示例中的 MODEL_ID 需要替换

本文不预设某个语言模型已经可用。请先确认当前密钥可以访问的对话模型；图像模型不能用于对话接口。返回空的 data 时，先检查密钥权限与分组。

对话与流式输出

将 MODEL_ID 替换为查询到的对话模型。参数支持情况由所选模型决定；可以先只提供模型和消息，使用模型默认配置。

CURL · 普通对话

curl --fail-with-body https://mulinapi.com/v1/chat/completions \
  -H "Authorization: Bearer $MULIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "你好，暮临。"}
    ],
    "stream": false
  }'

普通响应的文本位于 choices[0].message.content。多轮对话需要在 messages 中按顺序携带此前的用户消息与助手回复。

逐段接收回复 · SSE

设置 "stream": true，用 curl -N 关闭输出缓冲。客户端按空行拆分 SSE 事件，再解析各事件的 data: 内容。

CURL · 流式对话

curl -N --fail-with-body https://mulinapi.com/v1/chat/completions \
  -H "Authorization: Bearer $MULIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "写一段关于暮色的短诗。"}],
    "stream": true
  }'

SSE · 事件内容示意

data: {"choices":[{"delta":{"content":"暮色"},"index":0}]}

data: {"choices":[{"delta":{"content":"落在城墙上。"},"index":0}]}

data: [DONE]

拼接 choices[0].delta.content 中存在的文本，遇到 [DONE] 结束。网络数据块不一定与事件边界一致，需保留尚未完整接收的内容。

图像生成

NovelAI 文生图使用 OpenAI 兼容图片接口，扩展参数放在 parameters 中。以下示例使用 V5 Curated；是否可调用仍以当前密钥权限为准。网页试炼场采用 Curated 模型，Full 模型继续保留 API 调用。

CURL · NOVELAI V5 CURATED

curl --fail-with-body https://mulinapi.com/v1/images/generations \
  -H "Authorization: Bearer $MULIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nai-diffusion-5-curated",
    "prompt": "a golden castle beside a peaceful winter lake",
    "size": "832x1216",
    "n": 1,
    "response_format": "b64_json",
    "parameters": {
      "steps": 23,
      "scale": 7,
      "sampler": "k_euler_ancestral",
      "negative_prompt": "blurry, low quality",
      "seed": 312759
    }
  }' -o image-response.json

保存生成结果

响应中的 data[].b64_json 是 PNG 的 Base64 数据。上面的请求将 JSON 写入本地文件，可以运行以下 Python 示例保存每张图片。

PYTHON · 解码 PNG

import base64
import json
from pathlib import Path

result = json.loads(Path("image-response.json").read_text(encoding="utf-8"))
for index, item in enumerate(result["data"], start=1):
    Path(f"image-{index}.png").write_bytes(base64.b64decode(item["b64_json"]))

及时保存原图

响应也会提供短时图片链接，约 5 分钟后过期。请保存 Base64 或下载图片；短时链接不适合作为长期图床。

使用 OpenAI Python SDK

安装 openai 后，通过 extra_body 传入 NovelAI 参数。环境变量沿用上方的 MULIN_API_KEY。

PYTHON · SDK

import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    base_url="https://mulinapi.com/v1",
    api_key=os.environ["MULIN_API_KEY"],
)
result = client.images.generate(
    model="nai-diffusion-4-5-full",
    prompt="a golden castle beside a peaceful winter lake",
    size="1024x1024",
    n=1,
    response_format="b64_json",
    extra_body={"parameters": {"steps": 23, "scale": 5}},
)
Path("image.png").write_bytes(base64.b64decode(result.data[0].b64_json))

NovelAI 绘图参数

以下范围适用于暮临当前 NovelAI 文生图入口。其他图像模型的参数以对应模型说明为准。

OpenAI 兼容请求字段
字段	填写方式
`model`	V4.5：`nai-diffusion-4-5-curated`、`nai-diffusion-4-5-full`。 V5：`nai-diffusion-5-curated`、`nai-diffusion-5-full`。请确认当前密钥有对应权限。
`prompt`	主提示词，描述整幅画面的内容、风格和总人数。
`size`	`宽x高`，如 `832x1216`；使用小写英文字母 `x`。
`n`	生成张数，整数 `1–4`。
`response_format`	填写 `b64_json`。
`parameters.steps`	采样步数，整数 `1–50`，默认 `23`。
`parameters.scale`	CFG 提示词引导强度，`0–10`；V4.5 默认 `5`，V5 默认 `7`。
`parameters.sampler`	采样器，默认 `k_euler_ancestral`，可选值见下方。
`parameters.negative_prompt`	负面提示词，描述不希望出现的内容。
`parameters.cfg_rescale`	CFG Rescale，`0–1`，默认 `0`。
`parameters.seed`	整数 `0–4294967295`；省略时随机。

可用采样器

k_euler_ancestralk_eulerk_dpmpp_2mk_dpmpp_2s_ancestralk_dpmpp_sdeddim_v3

画面规格与上限

标准尺寸
规格	可用尺寸 · 宽 × 高
Normal	832 × 1216 / 1216 × 832 / 1024 × 1024
Large	1024 × 1536 / 1536 × 1024
Wallpaper	1920 × 1088 / 1088 × 1920

自定义尺寸需要同时满足三项限制

最长边 ≤ 1920，总像素 ≤ 2,088,960，宽高均为 64 的倍数。例如 1472 × 1472 和 1536 × 1536 都超出面积上限。超限请求返回 HTTP 400，不生成图片、不扣费。

当前入口支持文生图与下方的 V4 角色提示词结构。暂不支持图生图、局部修复、参考图、Vibe 和 SMEA；请勿传入这些功能的参数。

多角色提示词

主提示词定义场景、风格和总人数；每个角色独立描述外貌、服饰与动作。V4.5 最多 6 个角色，V5 最多 22 个角色。角色数量本身不额外收费。

在 parameters 中添加 v4_prompt 与 v4_negative_prompt。两边的 char_captions 使用相同的角色顺序与位置；主正、负提示词也应与 base_caption 一致。

JSON · 完整双角色请求体

{
  "model": "nai-diffusion-5-curated",
  "prompt": "2people, garden, side-by-side",
  "size": "1216x832",
  "n": 1,
  "response_format": "b64_json",
  "parameters": {
    "steps": 23,
    "scale": 7,
    "negative_prompt": "blurry, low quality",
    "v4_prompt": {
      "caption": {
        "base_caption": "2people, garden, side-by-side",
        "char_captions": [
          {"char_caption": "adult woman, red hair, white dress",
           "centers": [{"x": 0.3, "y": 0.5}]},
          {"char_caption": "adult man, black hair, blue coat",
           "centers": [{"x": 0.7, "y": 0.5}]}
        ]
      },
      "use_coords": true,
      "use_order": true
    },
    "v4_negative_prompt": {
      "caption": {
        "base_caption": "blurry, low quality",
        "char_captions": [
          {"char_caption": "blue hair", "centers": [{"x": 0.3, "y": 0.5}]},
          {"char_caption": "red coat", "centers": [{"x": 0.7, "y": 0.5}]}
        ]
      },
      "legacy_uc": false
    }
  }
}

use_coords: true 启用手动定位，x 从左到右、y 从上到下，范围为 0–1；设为 false 由模型安排位置。V4.5 使用 5 × 5 位置网格，坐标取 0.1、0.3、0.5、0.7、0.9；V5 支持连续坐标。use_order: true 保留角色顺序。试炼场提供角色卡片与位置控件，也可直接查看生成的请求 JSON。

NovelAI 原生接口

原生格式使用 POST https://mulinapi.com/ai/generate-image，仍以你的暮临 API Key 鉴权，并从相同账户扣费。成功响应是包含图片的 ZIP 文件。

CURL · 保存 ZIP

curl --fail-with-body https://mulinapi.com/ai/generate-image \
  -H "Authorization: Bearer $MULIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "a golden castle beside a peaceful winter lake",
    "model": "nai-diffusion-4-5-full",
    "action": "generate",
    "parameters": {
      "width": 1024,
      "height": 1024,
      "steps": 23,
      "scale": 5,
      "n_samples": 1,
      "sampler": "k_euler_ancestral",
      "negative_prompt": "blurry, low quality",
      "seed": 312759
    }
  }' -o images.zip

原生客户端通常填写根地址 https://mulinapi.com；只有要求「完整接口地址」时才填写 /ai/generate-image 完整路径。原生格式用 input 传主提示词，用 parameters.width / height 指定尺寸，用 n_samples 指定张数。

请求失败时可能返回错误 JSON。请先检查 HTTP 状态与 curl 退出状态，再打开下载文件；文件扩展名为 .zip 不代表请求成功。

余烬与计费

NovelAI 标准尺寸 · 余烬 / 张
模型	Normal	Large	Wallpaper
V4.5 Curated / Full `nai-diffusion-4-5-curatednai-diffusion-4-5-full`	0.5	2	3.5
V5 Curated / Full `nai-diffusion-5-curatednai-diffusion-5-full`	1.5	3	5

同一版本的 Curated 与 Full 价格相同。标准尺寸按表中固定价计费，生成多张时按张数累计。对应像素尺寸见画面规格。

自定义尺寸如何计算

每张费用 = 同模型 Normal 单价 × 本次标称 Anlas ÷ Normal 默认标称 Anlas。默认 23 步时，V4.5 的基准为 17，V5 为 26。自定义尺寸的标称 Anlas 随分辨率和步数变化，采用订阅优惠前的点数。

例如 512 × 768、23 步的 V4.5 标称用量为 7 Anlas，每张约 0.2059 余烬（0.5 × 7 ÷ 17）。批量生成按张数累计，实际扣费以调用记录为准。

账户余额与密钥额度需要同时可用

账户有余烬，不代表某一枚密钥仍有额度；密钥设置无限额，也不代表账户可以透支。语言模型与其他图像模型的费用请查看模型目录。

排查问题

先检查 HTTP 状态与错误响应中的说明，再核对请求地址、模型 ID、参数及账户状态。

常见响应与处理
现象	检查项
`400` 参数错误	检查 JSON 格式、模型参数和尺寸。NovelAI 需要同时满足 1920 最长边、2,088,960 总像素、64 倍数限制。
`401 / 403` 鉴权或权限问题	确认使用暮临 API Key，完整传入 Bearer 请求头；核对密钥有效期、分组、模型权限和额度。
额度或余额不足	分别检查账户余烬余额与此枚 API Key 的剩余额度，并查看错误信息。
`404` 路径错误	检查是否重复追加 /v1；原生接口路径是 /ai/generate-image，前面不加 /v1。
`429` 忙碌或频率限制	减少并发，稍后再试。NovelAI 忙时也会返回 429，请避免立即连续重发。
`5xx` 服务或上游错误	记录请求时间与错误内容，结合调用记录检查。NovelAI 服务不会自动重试失败的生成。
模型列表为空 / 找不到模型	检查该密钥的分组与模型权限。不要把本文的 MODEL_ID 占位符作为真实模型名发送。
短时图片链接打不开	链接可能已过期；使用已经保存的 b64_json 数据解码，或及时下载原图。

网络超时无法单独说明生成是否已经完成。重新发送前请先查看调用记录，避免重复生成和重复消费。

READY WHEN YOU ARE

让第一份请求，抵达。

先在网页试炼场确认参数，再接入你的应用。

进入试炼场

从此处，接续灵感。

快速开始

准备示例环境

查询可用模型

对话与流式输出

逐段接收回复 · SSE

图像生成

保存生成结果

使用 OpenAI Python SDK

NovelAI 绘图参数

画面规格与上限

多角色提示词

NovelAI 原生接口

余烬与计费

自定义尺寸如何计算

排查问题

让第一份请求，抵达。

正在准备使用声明

进入暮临之前

地区限制说明

关于我们的服务

理解生成结果与服务边界

妥善处理输入与内容

了解余烬与退款规则

你已拒绝使用声明