NovelAI APIのつらみについて書く
プロンプトをinputとbase_captionの2か所に書かされる！？エラーはほぼ500。つらさ5つと自作SDKの宣伝です
あいさつ
どうも、Caruです。最近急に寒くなってきましたね(2025/10/24)。私のPC部屋では未だに冷房がないと灼熱地獄ですが(笑)。
皆様も体調にお気をつけください。
さて、たまには記事を書こうということで、NovelAIのAPIを使って画像生成をするときの辛い点をまとめてみようと思います。
1. APIドキュメントがひどい
NovelAIのAPIドキュメントというか、OpenAPIの定義がひどいです。 まず、最初、このURL
が検索ででてきたので、てっきりこれで画像生成ができる！と思ったのですが、大間違い。 こんなことが説明に書いてあります。
IMPORTANT: Existing and new API users must read the upcoming generation-specific documentation:
Image Generation documentation: https://image.novelai.net/docs/index.html
Text Generation documentation: https://text.novelai.net/docs/index.htmlいや、エンドポイント違うんかい(笑)。で、TextのAPIは一旦置いておいて、ImageのAPIを見てみます。
まあ、URLが通常のSwaggerのパスじゃないのもムカつくのですが、一応ここに定義がのっています。
一件落着かと思いきや、問題はまだまだ続きます。
ai/generate-image-streamを見ると、こんなことが書いてあります。
定義がない！！
フィールド: json[object]じゃないねん。Exampleに申し訳程度のスキーマ？的なものが貼ってありますが残念。これでは動きません。
なので、NovelAIのサイト上で自分であらゆるモデルのバージョンやパラメータを試して、 DevToolsで同じエンドポイントへのペイロードを見て、それを参考に自分で定義を作成する必要があります。
2. パラメータの説明がない
パラメータの説明はないため、サイト上で試すときに一つ一つのパラメータがなにを意味するかを理解する必要があります。 ちなみに私はかなり時間をかけてやりましたが、未だにすべてのパラメータの意味を理解していません。
3. データ構造がひどい
これはかなりイライラするのですが、NovelAIのAPIはデータ構造がひどいです。
まず、ai/generate-image-streamのペイロードの冒頭はこんな感じです。
{
"action": "string",
"input": "string",
"model": "string",
...
}actionはgenerate、inputはプロンプト(+)、modelはモデルの名前です。
もう少し進みます。
"v4_prompt": {
"caption": {
"base_caption": "string",
"char_captions": [
{
"centers": [
{
"x": 0,
"y": 0
}
],
"char_caption": "string"
}
]
},
...
}さっきプロンプト(+)記入したじゃん！？
そうです。NovelAI V4以降、キャラクター定義が追加されて、キャラクターの定義をプロンプト(+)と別の場所に分けて記入する必要がありました。
で、char_captionsはcharacterPrompts(ドキュメント未記載😡)とほぼ等価のキャラクターの定義ですね。
では、base_captionは何でしょうか？
じつは、base_captionはプロンプト(+)です。
ですので、自分でデータを作成しようと思ったら、わざわざinputをbase_captionにコピーする必要があります。
本当にひどいですね。
スパゲッティコードならぬ、スパゲッティjsonです...(笑)
4. フィールド名の命名規則がバラバラ
その4. どうやって開発してるんだこれは？
フィールド名の命名規則がCamelCaseだったり、snake_caseだったり、バラバラです。
例えば、n_samplesもあれば、ucPresetもあります。
5. エラーがわかりにくい
特に簡単なエラー(モデルがないとか)はたまに400でエラーがなにか教えてくれることがあります。
しかし、ほとんどの場合は、500エラーでエラーがなにか教えてくれません。もう私はここで挫折しました。
まとめと宣伝
NovelAIのAPIはかなりひどいです。 ですが、生成できる画像の品質は世界中のどのAIサービスにも劣らない素晴らしいものです。
だからこそ、このエコシステムを自分ができる限り良くしたいという思いがあります。
そこで、私はNovelAIのAPIを使用するためのPythonライブラリnovelai-sdkを開発しております！
Pydantic v2による型安全で整理されたデータ構造や、モデル名や属性の補完など使いやすさを一切妥協せずに開発しています。
他のライブラリでは使えないキャラクター参照にも対応していますので、ぜひ使ってみてください!
インストールは
pip install novelai-sdkまたは
uv add novelai-sdkでインストールできます！
それでは、今回はここまでです。 ではでは。
