Narzędzia LangChain i LangGraph

langchain-popnow daje agentom LangChain i LangGraph narzędzia do tworzenia obrazów, wideo, muzyki i mowy z modelami PopNow, a także narzędzia do listowania modeli, pobierania zadań i sprawdzania salda API. Jeden klucz API obsługuje każdy model, od Nano Banana i Seedream po MiniMax H3, Kling, Suno i Gemini TTS.

Każde płatne wywołanie najpierw dostaje wycenę w USD. Płatne narzędzie wywołane bez max_usd tylko zwraca cenę: nic nie jest tworzone i nic nie jest naliczane. Pakiet ma otwarty kod na licencji MIT (GitHub) i jest zbudowany na oficjalnym SDK dla Pythona.

Przegląd

Konfiguracja

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

Gdy agent wywoła narzędzie z ToolCall, narzędzie zwraca ToolMessage, którego content to powyższe podsumowanie JSON, a artifact to pełny zapis zadania lub wyceny PopNow.

Narzędzia

PopNowToolkit().get_tools() zwraca wszystkie osiem z jedną wspólną konfiguracją.

Narzędzia generowania przyjmują wspólne pola (prompt, aspect_ratio, resolution, duration_seconds, voice_id i tak dalej), opcjonalne model, by wybrać inny model PopNow, oraz extra_input dla każdego pola, które popnow_list_models podaje dla tego modelu. ID modeli mają wzór <maker>/<model>/<task> opisany w Modelach.

Jak działa zatwierdzanie

Zadania PopNow są asynchroniczne: wycena, utworzenie po zatwierdzonej cenie, potem czekanie na wynik. Narzędzia idą tym samym przebiegiem co serwer MCP dla deweloperów:

1. Wycena. Agent wywołuje płatne narzędzie bez max_usd. Narzędzie prosi PopNow o wycenę i zwraca status: "needs_confirmation" z cost_usd. Nic nie jest tworzone ani wstrzymywane.
2. Zatwierdzenie. Agent pokazuje cenę użytkownikowi. Po zatwierdzeniu wywołuje narzędzie ponownie z tymi samymi argumentami i max_usd ustawionym na wycenione cost_usd.
3. Uruchomienie. Jeśli aktualna wycena mieści się w max_usd, zadanie zostaje utworzone z zablokowaną wyceną, a narzędzie czeka na wynik. Jeśli cena wzrosła, narzędzie zwraca nowe needs_confirmation i niczego nie nalicza.

Wyniki zawierają podpisane linki do pobrania, które wygasają, oraz URI popnow://g/<task>/<n>, który nie wygasa i może być przekazany innemu narzędziu PopNow, na przykład do animacji wygenerowanego obrazu. Długie wideo może wciąż trwać, gdy skończy się wait_timeout (domyślnie 600 sekund): narzędzie zwraca wtedy status: "running" z task_id, a popnow_get_task odbierze wynik później. Zadania nieudane lub wygasłe zwalniają blokadę i nic nie kosztują.

Limity wydatków

Ustaw je w dowolnym płatnym narzędziu albo w PopNowToolkit:

Obowiązują też limity wydatków i lista dozwolonych modeli klucza API, ustawione w konsoli API.

Użycie z agentem 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)

Agent może działać na dowolnym modelu czatu obsługiwanym przez LangChain, w tym na modelach czatu PopNow przez endpoint zgodny z OpenAI https://api.popnow.ai/v1.

Użycie z 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 nadal działa w LangGraph 1.x; nowe projekty mogą użyć langchain.agents.create_agent, jak pokazano wyżej. Do twardego kroku zatwierdzenia przez człowieka połącz narzędzia z HumanInTheLoopMiddleware z LangChain albo z interrupt z LangGraph.

Więcej przykładów

Znajdź model i jego pola wejściowe

Listowanie modeli jest bezpłatne. Z model narzędzie zwraca pola wejściowe tego modelu i ceny:

from langchain_popnow import PopNowListModels

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

Animuj obraz wybranym modelem

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

Lektorowanie bez potwierdzania każdej linijki

Lektor kosztuje ułamek centa, więc proces może sam zatwierdzać małe wyceny:

from langchain_popnow import PopNowSpeech

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

Dowolny model po ID

PopNowCreateTask wysyła własne input modelu, dokładnie tak jak w Zadaniach:

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

Każde narzędzie działa też asynchronicznie: await tool.ainvoke(...).

Ceny

Listowanie modeli, odczyt zadań i sprawdzanie salda są bezpłatne. Narzędzia generowania naliczają cenę modelu w USD z twojego salda API: zadanie blokuje wycenioną cenę przy przyjęciu i rozlicza rzeczywistą kwotę po zakończeniu. Zadania nieudane lub wygasłe nic nie kosztują.

popnow_list_models zwraca stawki w USD dla każdego modelu. Cena każdego modelu jest na stronie Modele i na jego własnej stronie; indeks cen AI też je zawiera. Jak działają wyceny, blokady i zwroty: Rozliczenia API i wyceny.

Częste błędy

Pełna lista jest na stronie Kody błędów.

Czy to działa z LangGraph?

Tak. Narzędzia są standardowymi narzędziami LangChain, więc create_react_agent, ToolNode i własne grafy LangGraph mogą je wywoływać. Jeśli każdą cenę ma zatwierdzać człowiek, połącz je z interrupt z LangGraph.

Czy agent może wydać moje saldo bez pytania?

Domyślnie nie. Płatne narzędzie wywołane bez max_usd tylko zwraca wycenę. Wydawanie bez zatwierdzenia jest możliwe tylko wtedy, gdy ustawisz auto_approve_usd, a max_usd_per_call oraz limity wydatków klucza nadal obowiązują.

Których modeli mogą używać narzędzia?

Dowolnego modelu obrazów, wideo lub audio z katalogu. Narzędzia generowania mają rozsądne wartości domyślne; podaj model, by wybrać inny, albo użyj PopNowCreateTask z dowolnym ID modelu. popnow_list_models pokazuje ID bezpośrednio z poziomu agenta.

Czy jest wersja dla JavaScriptu?

Dla TypeScriptu i JavaScriptu użyj providera Vercel AI SDK albo SDK dla JavaScriptu.

Powiązane