Herramientas para LangChain y LangGraph

langchain-popnow da a los agentes de LangChain y LangGraph herramientas que crean imágenes, videos, música y voz con modelos de PopNow, y herramientas que listan modelos, consultan tareas y revisan el saldo de la API. Una sola clave de API cubre todos los modelos, desde Nano Banana y Seedream hasta MiniMax H3, Kling, Suno y Gemini TTS.

Cada llamada de pago se cotiza primero en USD. Una herramienta de pago llamada sin max_usd solo devuelve el precio: no se crea nada y no se cobra nada. El paquete es de código abierto bajo licencia MIT (GitHub) y está construido sobre el SDK oficial de Python.

De un vistazo

Configuración

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

Cuando un agente llama a la herramienta con un ToolCall, la herramienta devuelve un ToolMessage cuyo content es el resumen JSON de arriba y cuyo artifact es el registro completo de la tarea o de la cotización en PopNow.

Herramientas

PopNowToolkit().get_tools() devuelve las ocho con una sola configuración compartida.

Las herramientas de generación aceptan los campos comunes (prompt, aspect_ratio, resolution, duration_seconds, voice_id y los demás), un model opcional para elegir otro modelo de PopNow, y extra_input para cualquier campo que popnow_list_models liste para ese modelo. Los IDs de modelo siguen el patrón <maker>/<model>/<task> que se describe en Modelos.

Cómo funciona la aprobación

Las tareas de PopNow son asíncronas: se cotizan, se crean al precio aprobado y después se espera el resultado. Las herramientas siguen el mismo flujo que el servidor MCP para desarrolladores:

1. Cotización. El agente llama a una herramienta de pago sin max_usd. La herramienta pide a PopNow una cotización y devuelve status: "needs_confirmation" con cost_usd. No se crea ni se retiene nada.
2. Aprobación. El agente muestra el precio al usuario. Tras la aprobación, vuelve a llamar a la herramienta con los mismos argumentos más max_usd igual al cost_usd cotizado.
3. Ejecución. Si la cotización vigente está dentro de max_usd, la tarea se crea con esa cotización bloqueada y la herramienta espera el resultado. Si el precio subió, la herramienta devuelve un nuevo needs_confirmation y no cobra nada.

Los resultados contienen enlaces de descarga firmados, que caducan, y un URI popnow://g/<task>/<n> que no caduca y se puede pasar a otra herramienta de PopNow, por ejemplo para animar una imagen generada. Un video largo puede seguir en curso cuando termina wait_timeout (por defecto 600 segundos): en ese caso la herramienta devuelve status: "running" con un task_id, y popnow_get_task recoge el resultado más tarde. Las tareas fallidas o caducadas liberan la retención y no cuestan nada.

Límites de gasto

Configúralos en cualquier herramienta de pago o en PopNowToolkit:

Los topes de gasto y la lista de modelos permitidos de la clave de API, configurados en la consola de API, se aplican también.

Uso con un agente de 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)

El agente puede funcionar con cualquier modelo de chat que admita LangChain, incluidos los modelos de chat de PopNow a través del endpoint compatible con OpenAI https://api.popnow.ai/v1.

Uso con 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 sigue funcionando en LangGraph 1.x; los proyectos nuevos pueden usar langchain.agents.create_agent, como en el ejemplo de arriba. Para un paso de aprobación humana estricto, combina las herramientas con HumanInTheLoopMiddleware de LangChain o con un interrupt de LangGraph.

Más ejemplos

Busca un modelo y sus entradas

Listar modelos es gratis. Con model, la herramienta devuelve los campos de entrada y los precios de ese modelo:

from langchain_popnow import PopNowListModels

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

Anima una imagen con un modelo elegido

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

Locuciones sin aprobar cada línea

Una locución cuesta una fracción de centavo, así que un pipeline puede aprobar por sí solo cotizaciones pequeñas:

from langchain_popnow import PopNowSpeech

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

Cualquier modelo por ID

PopNowCreateTask envía el input propio de un modelo, exactamente como en Tareas:

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 las herramientas también se ejecutan de forma asíncrona: await tool.ainvoke(...).

Precios

Listar modelos, leer tareas y consultar el saldo son gratis. Las herramientas de generación cobran la tarifa en USD del modelo a tu saldo de la API: una tarea retiene su precio cotizado al ser aceptada y liquida el cargo real al terminar. Las tareas fallidas o caducadas no cuestan nada.

popnow_list_models devuelve las tarifas en USD de cada modelo. El precio de cada modelo está en Modelos y en su propia página; el índice de precios de IA también los lista. Cómo funcionan las cotizaciones, las retenciones y los reembolsos: Facturación y cotizaciones.

Errores comunes

La lista completa está en Errores.

¿Funciona con LangGraph?

Sí. Las herramientas son herramientas estándar de LangChain, así que create_react_agent, ToolNode y los grafos personalizados de LangGraph pueden llamarlas. Combínalas con un interrupt de LangGraph si una persona debe aprobar cada precio.

¿Puede un agente gastar mi saldo sin preguntar?

No por defecto. Una herramienta de pago llamada sin max_usd solo devuelve una cotización. El gasto sin aprobación ocurre únicamente si configuras auto_approve_usd, y max_usd_per_call junto con los topes de gasto de la clave siguen aplicándose.

¿Qué modelos pueden usar las herramientas?

Cualquier modelo de imagen, video o audio del catálogo. Las herramientas de generación tienen valores por defecto razonables; pasa model para elegir otro, o usa PopNowCreateTask con cualquier ID de modelo. popnow_list_models lista los IDs desde dentro del agente.

¿Hay una versión en JavaScript?

Para TypeScript y JavaScript, usa el proveedor del Vercel AI SDK o el SDK de JavaScript.

Relacionados