LangChain 與 LangGraph 工具

langchain-popnow 為 LangChain 與 LangGraph 代理提供工具：可用 PopNow 模型生成圖片、影片、音樂與語音，也可以列出模型、領取任務結果、查詢 API 餘額。一把 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() 會以同一組設定回傳全部八個工具。

生成類工具接受共用欄位（prompt、aspect_ratio、resolution、duration_seconds、voice_id 等）、可選的 model（用來選擇其他 PopNow 模型），以及 extra_input（用來傳入 popnow_list_models 為該模型列出的任意欄位）。模型 ID 遵循 模型中說明的 <maker>/<model>/<task> 格式。

審批如何運作

PopNow 任務是非同步的：先報價，依確認的價格建立，然後等待結果。這些工具的流程與面向開發者的 MCP 伺服器相同：

1. 報價。 代理不帶 max_usd 呼叫付費工具。工具向 PopNow 請求報價，並回傳 status: "needs_confirmation" 與 cost_usd。此時不會建立或凍結任何金額。
2. 確認。 代理把價格展示給使用者。使用者確認後，它以相同的參數再次呼叫工具，並把 max_usd 設為報價的 cost_usd。
3. 執行。 如果目前的報價不超過 max_usd，任務會以該報價鎖定價格建立，工具隨後等待結果。如果價格上漲，工具會回傳新的 needs_confirmation，且不收取任何費用。

結果中包含會過期的簽名下載連結，以及不會過期的 popnow://g/<task>/<n> 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",
})

不必逐行確認的旁白配音

旁白配音的費用只有幾分之一美分，因此流程可以自行確認小額報價：

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。

相關內容