Ferramentas para LangChain e LangGraph

langchain-popnow dá aos agentes de LangChain e LangGraph ferramentas que criam imagens, vídeos, músicas e voz com modelos do PopNow, e ferramentas que listam modelos, consultam tarefas e verificam o saldo da API. Uma única chave de API cobre todos os modelos, do Nano Banana e Seedream ao MiniMax H3, Kling, Suno e Gemini TTS.

Cada chamada paga é cotada primeiro em USD. Uma ferramenta paga chamada sem max_usd só retorna o preço: nada é criado e nada é cobrado. O pacote é de código aberto sob licença MIT (GitHub) e é construído sobre o SDK oficial de Python.

Resumo

Configuração

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

Quando um agente chama a ferramenta com um ToolCall, a ferramenta retorna um ToolMessage cujo content é o resumo JSON acima e cujo artifact é o registro completo da tarefa ou da cotação no PopNow.

Ferramentas

PopNowToolkit().get_tools() retorna as oito com uma única configuração compartilhada.

As ferramentas de geração aceitam os campos comuns (prompt, aspect_ratio, resolution, duration_seconds, voice_id e assim por diante), um model opcional para escolher outro modelo do PopNow, e extra_input para qualquer campo que popnow_list_models listar para aquele modelo. Os IDs de modelo seguem o padrão <maker>/<model>/<task> descrito em Modelos.

Como funciona a aprovação

As tarefas do PopNow são assíncronas: cota-se, cria-se pelo preço aprovado e depois se espera o resultado. As ferramentas seguem o mesmo fluxo do servidor MCP para desenvolvedores:

1. Cotação. O agente chama uma ferramenta paga sem max_usd. A ferramenta pede uma cotação ao PopNow e retorna status: "needs_confirmation" com cost_usd. Nada é criado nem reservado.
2. Aprovação. O agente mostra o preço ao usuário. Depois da aprovação, chama a ferramenta de novo com os mesmos argumentos, mais max_usd igual ao cost_usd cotado.
3. Execução. Se a cotação atual estiver dentro de max_usd, a tarefa é criada com essa cotação travada e a ferramenta espera o resultado. Se o preço subiu, a ferramenta retorna um novo needs_confirmation e nada é cobrado.

Os resultados contêm links de download assinados, que expiram, e um URI popnow://g/<task>/<n> que não expira e pode ser passado a outra ferramenta do PopNow, por exemplo para animar uma imagem gerada. Um vídeo longo pode ainda estar em execução quando o wait_timeout (padrão de 600 segundos) termina: nesse caso a ferramenta retorna status: "running" com um task_id, e popnow_get_task recolhe o resultado depois. Tarefas com falha ou expiradas liberam a reserva e não custam nada.

Limites de gasto

Defina-os em qualquer ferramenta paga ou em PopNowToolkit:

Os limites de gasto e a lista de modelos permitidos da chave de API, definidos no console de API, também se aplicam.

Uso com um agente do 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)

O agente pode rodar em qualquer modelo de chat que o LangChain suporte, inclusive os modelos de chat do PopNow pelo endpoint compatível com OpenAI https://api.popnow.ai/v1.

Uso com 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 continua funcionando no LangGraph 1.x; projetos novos podem usar langchain.agents.create_agent, como no exemplo acima. Para uma etapa de aprovação humana rigorosa, combine as ferramentas com o HumanInTheLoopMiddleware do LangChain ou com um interrupt do LangGraph.

Mais exemplos

Encontre um modelo e os seus campos

Listar modelos é grátis. Com model, a ferramenta retorna os campos de entrada e os preços desse modelo:

from langchain_popnow import PopNowListModels

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

Anime uma imagem com um modelo escolhido

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

Narrações sem aprovar cada linha

Uma narração custa uma fração de centavo, então um pipeline pode aprovar sozinho cotações pequenas:

from langchain_popnow import PopNowSpeech

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

Qualquer modelo pelo ID

PopNowCreateTask envia o input próprio de um modelo, exatamente como em Tarefas:

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

Todas as ferramentas também rodam de forma assíncrona: await tool.ainvoke(...).

Preços

Listar modelos, ler tarefas e consultar o saldo são grátis. As ferramentas de geração cobram a tarifa em USD do modelo do seu saldo da API: uma tarefa reserva o preço cotado quando é aceita e liquida a cobrança real ao terminar. Tarefas com falha ou expiradas não custam nada.

popnow_list_models retorna as tarifas em USD de cada modelo. O preço de cada modelo está em Modelos e na página de cada um; o índice de preços de IA também os lista. Como funcionam as cotações, as reservas e os reembolsos: Cobrança e cotações.

Erros comuns

A lista completa está em Erros.

Funciona com LangGraph?

Sim. As ferramentas são ferramentas padrão do LangChain, então create_react_agent, ToolNode e grafos personalizados do LangGraph podem chamá-las. Combine-as com um interrupt do LangGraph se uma pessoa precisar aprovar cada preço.

Um agente pode gastar meu saldo sem perguntar?

Não por padrão. Uma ferramenta paga chamada sem max_usd só retorna uma cotação. O gasto sem aprovação só acontece se você definir auto_approve_usd, e max_usd_per_call junto com os limites de gasto da chave continuam valendo.

Quais modelos as ferramentas podem usar?

Qualquer modelo de imagem, vídeo ou áudio do catálogo. As ferramentas de geração têm padrões sensatos; passe model para escolher outro, ou use PopNowCreateTask com qualquer ID de modelo. popnow_list_models lista os IDs de dentro do agente.

Existe uma versão em JavaScript?

Para TypeScript e JavaScript, use o provedor do Vercel AI SDK ou o SDK de JavaScript.

Relacionados