Инструменты LangChain и LangGraph

langchain-popnow даёт агентам LangChain и LangGraph инструменты для создания изображений, видео, музыки и речи с моделями PopNow, а также инструменты для списка моделей, получения задач и проверки баланса API. Один ключ API работает со всеми моделями: от Nano Banana и Seedream до MiniMax H3, Kling, Suno и Gemini TTS.

Каждый платный вызов сначала получает расчёт стоимости в USD. Платный инструмент, вызванный без max_usd, только возвращает цену: ничего не создаётся и ничего не списывается. Пакет распространяется под лицензией MIT с открытым кодом (GitHub) и построен на официальном SDK для Python.

Обзор

Настройка

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 и ничего не списывает.

В результатах лежат подписанные ссылки на скачивание: они истекают. Также есть URI вида popnow://g/<task>/<n>, который не истекает и может быть передан другому инструменту 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, в том числе на чат-моделях PopNow через совместимый с OpenAI эндпоинт https://api.popnow.ai/v1.

Использование с 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, как показано выше. Для жёсткого шага подтверждения человеком объедините инструменты с HumanInTheLoopMiddleware из LangChain или с interrupt из LangGraph.

Ещё примеры

Найдите модель и её входные поля

Список моделей бесплатен. С 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(...).

Цены

Список моделей, чтение задач и проверка баланса бесплатны. Инструменты генерации списывают цену модели в USD с вашего баланса API: задача удерживает зафиксированный расчёт при принятии и окончательно списывает фактическую сумму по завершении. Задачи с ошибкой или истёкшие ничего не стоят.

popnow_list_models возвращает курсы в USD для каждой модели. Цена каждой модели указана на странице Модели и на её собственной странице; индекс цен AI тоже их содержит. Как работают расчёты, удержания и возвраты: Оплата API и расчёт стоимости.

Частые ошибки

Полный список есть на странице Коды ошибок.

Работает ли это с LangGraph?

Да. Инструменты — стандартные инструменты LangChain, поэтому create_react_agent, ToolNode и собственные графы LangGraph могут их вызывать. Если человек должен подтверждать каждую цену, добавьте interrupt из LangGraph.

Может ли агент тратить мой баланс без спроса?

По умолчанию нет. Платный инструмент, вызванный без max_usd, только возвращает расчёт. Расходы без подтверждения возможны только если вы задали auto_approve_usd; при этом по-прежнему действуют max_usd_per_call и ограничители расходов ключа.

Какие модели могут использовать инструменты?

Любую модель генерации изображений, видео или аудио из каталога. У инструментов генерации разумные значения по умолчанию; передайте model, чтобы выбрать другую модель, или используйте PopNowCreateTask с любым ID модели. popnow_list_models показывает ID прямо внутри агента.

Есть ли версия для JavaScript?

Для TypeScript и JavaScript используйте провайдер Vercel AI SDK или SDK для JavaScript.

Связанное