LangChain と LangGraph のツール

langchain-popnow は、LangChain と LangGraph のエージェントに、PopNow のモデルで画像・動画・音楽・音声を作るツールを提供します。モデル一覧、タスクの取得、API 残高の確認を行うツールも含まれます。1 つの API キーで、Nano Banana や Seedream から MiniMax H3、Kling、Suno、Gemini TTS まですべてのモデルを使えます。

有料の呼び出しはすべて、まず米ドルで見積もられます。max_usd を指定せずに有料ツールを呼ぶと、価格が返されるだけです。何も作成されず、課金も発生しません。このパッケージは MIT ライセンスのオープンソースで（GitHub）、公式の Python SDK を基に作られています。

概要

セットアップ

pip install -U langchain-popnow

export POPNOW_API_KEY="sk-popnow-..."

from langchain_popnow import PopNowImageGeneration

tool = PopNowImageGeneration()

# 1. Quote: returns the price, starts nothing.
print(tool.invoke({"prompt": "A small red fox curled up in a teacup, soft morning light"}))
# {"status": "needs_confirmation", "model": "google/nano-banana-2.1/text-to-image", "cost_usd": "0.048", ...}

# 2. Approved: creates the task and waits for it.
print(tool.invoke({"prompt": "A small red fox curled up in a teacup, soft morning light", "max_usd": "0.048"}))
# {"status": "succeeded", "task_id": "...", "cost_usd": "0.048", "outputs": [{"url": "https://...", "uri": "popnow://g/.../0"}], ...}

エージェントが ToolCall でツールを呼び出すと、ツールは ToolMessage を返します。その content は上記の JSON の要約で、artifact には PopNow のタスクまたは見積もりの完全なレコードが入ります。

ツール

PopNowToolkit().get_tools() を使うと、共通の設定で 8 つすべてのツールが返されます。

生成系のツールは、共通の項目（prompt、aspect_ratio、resolution、duration_seconds、voice_id など）、別のモデルを選ぶための任意の model、そして popnow_list_models がそのモデル向けに一覧した任意の項目を渡す extra_input を受け付けます。モデル ID は モデルで説明している <maker>/<model>/<task> の形式に従います。

承認の流れ

PopNow のタスクは非同期です。見積もり、承認された価格での作成、結果の待機という順に進みます。これらのツールは、開発者向け MCP サーバーと同じ流れに従います。

1. 見積もり。 エージェントは max_usd を付けずに有料ツールを呼びます。ツールは PopNow に見積もりを依頼し、status: "needs_confirmation" と cost_usd を返します。このとき、何も作成されず、保留もされません。
2. 承認。 エージェントは価格をユーザーに提示します。承認されたら、同じ引数に、見積もられた cost_usd を max_usd として加えて、もう一度ツールを呼びます。
3. 実行。 現在の見積もりが max_usd 以内であれば、その見積もりを固定してタスクが作成され、ツールは結果を待ちます。価格が上がっていた場合、ツールは新しい needs_confirmation を返し、何も課金されません。

結果には、期限切れになる署名付きのダウンロード URL と、期限切れにならない popnow://g/<task>/<n> の URI が含まれます。この URI は別の PopNow ツールに渡せ、たとえば生成した画像を動かすことに使えます。長い動画は wait_timeout（既定値は 600 秒）が過ぎても実行中のことがあります。その場合、ツールは status: "running" と task_id を返し、後で popnow_get_task で結果を取得できます。失敗したタスクや期限切れのタスクは保留を解放し、課金されません。

支出のガード

これらは、有料ツールや PopNowToolkit のどれにでも設定できます。

API コンソールで設定した API キーの利用上限とモデルの許可リストも、同じように適用されます。

LangChain のエージェントで使う

from langchain.agents import create_agent
from langchain_popnow import PopNowToolkit

tools = PopNowToolkit(max_usd_per_call="1.00").get_tools()

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=tools,
    system_prompt=(
        "You create media with PopNow tools. Paid tools return a price first: "
        "show it to the user and only call again with max_usd after they approve."
    ),
)

result = agent.invoke({"messages": [{"role": "user", "content": "Make a 9:16 clip of a vintage car on a coastal road"}]})
print(result["messages"][-1].content)

このエージェントは、LangChain が対応する任意のチャットモデルで動かせます。OpenAI 互換のエンドポイント https://api.popnow.ai/v1 経由の PopNow のチャットモデルも使えます。

LangGraph で使う

from langchain.chat_models import init_chat_model
from langgraph.prebuilt import create_react_agent
from langchain_popnow import PopNowToolkit

model = init_chat_model("anthropic:claude-sonnet-4-6")
agent = create_react_agent(model, PopNowToolkit(max_usd_per_call="1.00").get_tools())

for step in agent.stream(
    {"messages": [{"role": "user", "content": "Write a short lo-fi track for a cooking video and tell me the price first"}]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()

create_react_agent は LangGraph 1.x でも引き続き使えます。新しいプロジェクトでは、上で示した langchain.agents.create_agent を使ってください。人による承認を必ず挟みたい場合は、これらのツールと LangChain の HumanInTheLoopMiddleware、または LangGraph の interrupt を組み合わせてください。

その他の例

モデルと入力項目を調べる

モデルの一覧取得は無料です。model を指定すると、そのモデルの入力項目と価格が返されます。

from langchain_popnow import PopNowListModels

PopNowListModels().invoke({"modality": "video", "search": "kling"})
PopNowListModels().invoke({"model": "kling/3.0/image-to-video"})

選んだモデルで画像を動かす

from langchain_popnow import PopNowVideoGeneration

PopNowVideoGeneration().invoke({
    "prompt": "Gentle waves, slow push-in",
    "image_url": "https://example.com/beach.jpg",
    "model": "kling/3.0/image-to-video",
    "duration_seconds": 5,
    "max_usd": "0.50",
})

行ごとに承認しなくてよいナレーション

ナレーションの費用は 1 セントの数分の 1 程度なので、パイプラインは少額の見積もりを自動で承認できます。

from langchain_popnow import PopNowSpeech

speech = PopNowSpeech(auto_approve_usd="0.02")
speech.invoke({"text": "Welcome back to the channel!", "voice_id": "Kore"})

モデル ID で任意のモデルを使う

PopNowCreateTask は、モデル自身の input をそのまま送ります。タスクと同じ書き方です。

from langchain_popnow import PopNowCreateTask

PopNowCreateTask().invoke({
    "model": "alibaba/z-image-turbo/text-to-image",
    "input": {"prompt": "A paper boat on a puddle, overcast street, photo", "aspect_ratio": "1:1"},
    "max_usd": "0.02",
})

すべてのツールは非同期でも実行できます。await tool.ainvoke(...) と書きます。

料金

モデルの一覧取得、タスクの読み取り、残高の確認は無料です。生成系のツールは、モデルの米ドル料金を API 残高から課金します。タスクは受け付けられた時点で見積もり額を保留し、完了すると実際の料金で精算されます。失敗したタスクや期限切れのタスクは課金されません。

popnow_list_models は、各モデルの米ドル料金を返します。各モデルの価格はモデルのページと、各モデルのページに掲載されています。AI 価格指数にも一覧があります。見積もり、保留、返金の仕組みは課金と見積もりを参照してください。

よくあるエラー

完全な一覧はエラーにあります。

LangGraph でも使えますか？

はい。これらのツールは標準の LangChain ツールなので、create_react_agent、ToolNode、独自の LangGraph グラフから呼び出せます。料金ごとに人の承認が必要なら、LangGraph の interrupt と組み合わせてください。

エージェントが承認なしに残高を使ってしまうことはありますか？

既定では、ありません。max_usd を指定せずに有料ツールを呼ぶと、返されるのは見積もりだけです。承認なしで支払いが発生するのは auto_approve_usd を設定したときだけで、その場合も max_usd_per_call とキーの利用上限は適用されます。

ツールでどのモデルを使えますか？

カタログにある画像・動画・音声モデルであれば、どれでも使えます。生成系のツールには適切な既定値が設定されています。別のモデルを使うには model を渡すか、PopNowCreateTask でモデル ID を指定してください。popnow_list_models を使えば、エージェントの中からモデル ID を一覧できます。

JavaScript 版はありますか？

TypeScript と JavaScript では、Vercel AI SDK プロバイダーか JavaScript SDKを使ってください。

関連ページ