あいさつ
どうも、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ライブラリは他にもいくつか存在します。
| 機能 | novelai-sdk | novelai-api | novelai-python |
|---|---|---|---|
| V4モデル対応 | ✅ | ⚠️ | ✅ |
| キャラクター参照 | ✅ | ❌ | ✅ |
| ControlNet | ✅ | ❌ | ✅ |
| 型安全 (Pydantic v2) | ✅ | ❌ | ❌ |
| 非同期サポート | ✅ | ✅ | ✅ |
| メンテナンス状況 | 🟢 活発 | ⚠️ 限定的 | 🟢 活発 |
※ 2024年12月時点の情報です
5分でできる！クイックスタート
1. インストール
pip install novelai-sdkuvを使っている方はこちら：
uv add novelai-sdk2. 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
ぜひ使ってみてください！
リンク
それでは、良いAIライフを！
免責事項: これは非公式のクライアントライブラリです。NovelAIの公式製品ではありません。利用にはNovelAIの有効なサブスクリプションが必要です。
あいさつ
どうも、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ライブラリは他にもいくつか存在します。
| 機能 | novelai-sdk | novelai-api | novelai-python |
|---|---|---|---|
| V4モデル対応 | ✅ | ⚠️ | ✅ |
| キャラクター参照 | ✅ | ❌ | ✅ |
| ControlNet | ✅ | ❌ | ✅ |
| 型安全 (Pydantic v2) | ✅ | ❌ | ❌ |
| 非同期サポート | ✅ | ✅ | ✅ |
| メンテナンス状況 | 🟢 活発 | ⚠️ 限定的 | 🟢 活発 |
※ 2024年12月時点の情報です
5分でできる！クイックスタート
1. インストール
pip install novelai-sdkuvを使っている方はこちら：
uv add novelai-sdk2. 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
ぜひ使ってみてください！
リンク
それでは、良いAIライフを！
免責事項: これは非公式のクライアントライブラリです。NovelAIの公式製品ではありません。利用にはNovelAIの有効なサブスクリプションが必要です。