LangChain and LangGraph tools

langchain-popnow gives LangChain and LangGraph agents tools that create images, videos, music and speech with PopNow models, and tools that list models, collect tasks and check the API balance. One API key covers every model, from Nano Banana and Seedream to MiniMax H3, Kling, Suno and Gemini TTS.

Every paid call is quoted in USD first. A paid tool called without max_usd only returns the price: nothing is created and nothing is charged. The package is open source under the MIT license (GitHub) and built on the official Python SDK.

At a glance

Set up

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"}], ...}

When an agent calls the tool with a ToolCall, the tool returns a ToolMessage whose content is the JSON summary above and whose artifact is the full PopNow task or quote record.

Tools

PopNowToolkit().get_tools() returns all eight with one shared configuration.

The generation tools take the common fields (prompt, aspect_ratio, resolution, duration_seconds, voice_id and so on), an optional model to pick another PopNow model, and extra_input for any field that popnow_list_models lists for that model. Model IDs follow the <maker>/<model>/<task> pattern described in Models.

How approval works

PopNow tasks are asynchronous: quote, create at the approved price, then wait for the result. The tools follow the same flow as the developer MCP server:

1. Quote. The agent calls a paid tool without max_usd. The tool asks PopNow for a quote and returns status: "needs_confirmation" with cost_usd. Nothing is created or held.
2. Approve. The agent shows the price to the user. After approval it calls the tool again with the same arguments plus max_usd set to the quoted cost_usd.
3. Run. If the current quote is within max_usd, the task is created with that quote locked and the tool waits for the result. If the price went up, the tool returns a new needs_confirmation and charges nothing.

Results contain signed download URLs, which expire, and a popnow://g/<task>/<n> URI that does not expire and can be passed to another PopNow tool, for example to animate a generated image. A long video may still be running when wait_timeout (default 600 seconds) ends: the tool then returns status: "running" with a task_id, and popnow_get_task collects the result later. Failed or expired tasks release their hold and cost nothing.

Spending guards

Set these on any paid tool or on PopNowToolkit:

The spend caps and model allow-list of the API key, set in the API console, apply as well.

Use with a LangChain agent

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)

The agent can run on any chat model LangChain supports, including PopNow chat models through the OpenAI-compatible endpoint https://api.popnow.ai/v1.

Use with 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 still works in LangGraph 1.x; new projects can use langchain.agents.create_agent as shown above. For a hard human approval step, combine the tools with LangChain's HumanInTheLoopMiddleware or a LangGraph interrupt.

More examples

Find a model and its inputs

Listing models is free. With model, the tool returns that model's input fields and prices:

from langchain_popnow import PopNowListModels

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

Animate a picture with a chosen model

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",
})

Voiceovers without a prompt for every line

A voiceover costs a fraction of a cent, so a pipeline can approve small quotes on its own:

from langchain_popnow import PopNowSpeech

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

Any model by ID

PopNowCreateTask sends a model's own input, exactly as in Tasks:

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",
})

Every tool also runs asynchronously: await tool.ainvoke(...).

Pricing

Listing models, reading tasks and checking the balance are free. Generation tools charge the model's USD price to your API balance: a task holds its quoted price when it is accepted and settles the actual charge when it finishes. Tasks that fail or expire cost nothing.

popnow_list_models returns each model's USD rates. Every model's price is on Models and on its own model page; the AI price index lists them too. How quotes, holds and refunds work: Billing and quotes.

Common errors

The full list is in Errors.

Does it work with LangGraph?

Yes. The tools are standard LangChain tools, so create_react_agent, ToolNode and custom LangGraph graphs can call them. Pair them with a LangGraph interrupt if a person must approve each price.

Can an agent spend my balance without asking?

Not by default. A paid tool called without max_usd only returns a quote. Spending without approval happens only when you set auto_approve_usd, and max_usd_per_call plus the key's spend caps still apply.

Which models can the tools use?

Any image, video or audio model in the catalog. The generation tools have sensible defaults; pass model to pick another one, or use PopNowCreateTask with any model ID. popnow_list_models lists the IDs from inside the agent.

Is there a JavaScript version?

For TypeScript and JavaScript, use the Vercel AI SDK provider or the JavaScript SDK.

Related