NovelAI APIを簡単に使えるPython SDKを作った

あいさつ

どうも、Caruです！

以前の記事でNovelAI APIのつらみについて書きましたが、ついに解決策を完成させました。 novelai-sdkという、NovelAI APIを簡単に使うためのPythonライブラリです。

今回は、このSDKの紹介と使い方をまとめていきます。

なぜSDKを作ったのか

前回の記事でも触れましたが、NovelAI APIには以下のような問題がありました。

• APIドキュメントがほぼ存在しない
• パラメータの説明がない
• エラーメッセージが不親切（ほとんど500エラー）
• データ構造がスパゲッティ状態

正直、生のAPIを叩くのはかなりしんどいです。

「じゃあ、自分で作るしかないな」ということで、開発を始めました。

novelai-sdkの特徴

1. 型安全

Python 3.10以上をサポートし、Pydantic v2による堅牢なバリデーションを提供しています。 エディタでの補完が効くので、「このパラメータなんだっけ？」と悩む時間が大幅に減ります。

2. シンプルなAPI

from novelai import NovelAI
from novelai.types import GenerateImageParams
 
client = NovelAI()  # 環境変数からAPIキーを自動読み込み
 
params = GenerateImageParams(
    prompt="1girl, cat ears, masterpiece, best quality",
    model="nai-diffusion-4-5-full",
    size="portrait",
)
 
images = client.image.generate(params)
images[0].save("output.png")

これだけで画像生成ができます。生のAPIを叩くよりずっと楽ですよね。

3. 最新機能への対応

V4モデル、キャラクター参照（Character Reference）、ControlNetなど、NovelAIの最新機能にも対応しています。 特にキャラクター参照は他のライブラリではサポートされていないことが多いので、ここは力を入れました。

4. PIL/Pillow統合

生成された画像はPIL Imageとして返ってくるので、そのまま保存したり加工したりできます。 いちいちバイナリをデコードする必要はありません。

他のライブラリとの比較

NovelAI用のPythonライブラリは他にもいくつか存在します。

※ 2024年12月時点の情報です

5分でできる！クイックスタート

1. インストール

pip install novelai-sdk

uvを使っている方はこちら：

uv add novelai-sdk

2. APIキーの準備

NovelAIにログインして、アカウント設定 → アカウント → 永続的APIトークンを取得 からAPIキーを取得します。

取得したAPIキーを.envファイルに保存：

NOVELAI_API_KEY=pst-your-api-key-here

3. 画像を生成してみる

from novelai import NovelAI
from novelai.types import GenerateImageParams
 
# クライアント初期化（.envから自動でAPIキーを読み込み）
client = NovelAI()
 
# パラメータ設定
params = GenerateImageParams(
    prompt="1girl, cat ears, masterpiece, best quality",
    model="nai-diffusion-4-5-full",
    size="portrait", # (width, height)での指定もできます！
    steps=28,
    scale=5.0,
)
 
# 生成
print("画像を生成中...")
images = client.image.generate(params)
 
# 保存
if images:
    images[0].save("output.png")
    print("保存完了！")

これで完了です。簡単ですよね？

便利な機能たち

キャラクター参照

同じキャラクターの見た目を維持したまま、別のポーズや構図で生成できます。

詳しくは公式ドキュメントのCharacter Referenceを参照してください。

ControlNet

既存の画像から構図やポーズを引き継いで生成することができます。

ストリーミング生成

生成の進捗をリアルタイムで確認できるSSEストリーミングにも対応しています。

非同期クライアント

FastAPIやDiscord Botなどに簡単に組み込むことができます。

メタデータ

以前の記事で解説した通り、NovelAIで生成された画像にはPNG InfoとAlphaチャネルの両方にメタデータが埋め込まれています。

このSDKでは、メタデータの抽出・削除が簡単にできます。

from novelai.utils import extract_metadata, erase_metadata
 
# メタデータを抽出
meta = extract_metadata("image.png")
print(meta.png_info)   # PNG Infoから取得した情報
print(meta.alpha_info) # Alphaチャネルから取得した情報
 
# メタデータを削除
clean_image = erase_metadata("image.png", target="both")  # PNG Info + Alpha両方削除
clean_image.save("clean.png")

targetオプションで"alpha"、"png_info"、"both"を指定でき、削除したい対象を選べます。

まとめ

NovelAI APIの複雑な仕様を吸収して、誰でも簡単に画像生成ができるようにしたのがnovelai-sdkです。

• 型安全で補完が効く
• 最新機能に対応
• シンプルなAPI

ぜひ使ってみてください！

リンク

• GitHub Repository
• PyPI
• ドキュメント

それでは、良いAIライフを！

免責事項: これは非公式のクライアントライブラリです。NovelAIの公式製品ではありません。利用にはNovelAIの有効なサブスクリプションが必要です。