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。

相关内容