LangChain- und LangGraph-Tools

langchain-popnow gibt LangChain- und LangGraph-Agenten Tools, die Bilder, Videos, Musik und Sprache mit PopNow-Modellen erzeugen, dazu Tools, die Modelle auflisten, Tasks abfragen und das API-Guthaben prüfen. Ein API-Schlüssel genügt für jedes Modell, von Nano Banana und Seedream bis MiniMax H3, Kling, Suno und Gemini TTS.

Jeder kostenpflichtige Aufruf wird zuerst in USD bepreist. Ein kostenpflichtiges Tool, das ohne max_usd aufgerufen wird, liefert nur den Preis: Es wird nichts erstellt und nichts abgebucht. Das Paket ist Open Source unter der MIT-Lizenz (GitHub) und baut auf dem offiziellen Python-SDK auf.

Auf einen Blick

Einrichten

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

Ruft ein Agent das Tool mit einem ToolCall auf, gibt das Tool eine ToolMessage zurück. Ihr content ist die JSON-Zusammenfassung oben, ihr artifact der vollständige PopNow-Task- oder Angebotsdatensatz.

Tools

PopNowToolkit().get_tools() gibt alle acht mit einer gemeinsamen Konfiguration zurück.

Die Generierungs-Tools nehmen die gemeinsamen Felder (prompt, aspect_ratio, resolution, duration_seconds, voice_id und so weiter), optional ein model, um ein anderes PopNow-Modell zu wählen, und extra_input für jedes Feld, das popnow_list_models für dieses Modell auflistet. Modell-IDs folgen dem Muster <maker>/<model>/<task>, das unter Modelle beschrieben ist.

So funktioniert die Bestätigung

PopNow-Tasks laufen asynchron: bepreisen, zum bestätigten Preis anlegen, dann auf das Ergebnis warten. Die Tools folgen demselben Ablauf wie der Entwickler-MCP-Server:

1. Bepreisen. Der Agent ruft ein kostenpflichtiges Tool ohne max_usd auf. Das Tool fragt bei PopNow ein Angebot an und gibt status: "needs_confirmation" mit cost_usd zurück. Nichts wird angelegt oder reserviert.
2. Bestätigen. Der Agent zeigt dem Nutzer den Preis. Nach der Bestätigung ruft er das Tool mit denselben Argumenten erneut auf, zusätzlich mit max_usd auf dem angebotenen cost_usd.
3. Ausführen. Liegt das aktuelle Angebot innerhalb von max_usd, wird der Task mit diesem Angebot angelegt, und das Tool wartet auf das Ergebnis. Ist der Preis gestiegen, gibt das Tool ein neues needs_confirmation zurück und bucht nichts ab.

Ergebnisse enthalten signierte Download-URLs, die ablaufen, und eine URI popnow://g/<task>/<n>, die nicht abläuft und an ein anderes PopNow-Tool übergeben werden kann, etwa um ein erzeugtes Bild zu animieren. Ein langes Video kann noch laufen, wenn wait_timeout (Standard 600 Sekunden) abgelaufen ist: Das Tool gibt dann status: "running" mit einer task_id zurück, und popnow_get_task holt das Ergebnis später ab. Fehlgeschlagene oder abgelaufene Tasks geben ihre Reservierung frei und kosten nichts.

Ausgabenbremsen

Setze diese Optionen an jedem kostenpflichtigen Tool oder an PopNowToolkit:

Auch die Ausgabelimits und die Modell-Allowlist des API-Schlüssels, die in der API-Konsole eingestellt werden, gelten.

Mit einem LangChain-Agenten verwenden

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)

Der Agent kann mit jedem Chat-Modell laufen, das LangChain unterstützt, auch mit PopNow-Chat-Modellen über den OpenAI-kompatiblen Endpunkt https://api.popnow.ai/v1.

Mit LangGraph verwenden

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 funktioniert in LangGraph 1.x weiterhin; neue Projekte können langchain.agents.create_agent verwenden, wie oben gezeigt. Für einen harten Bestätigungsschritt durch einen Menschen kombinierst du die Tools mit HumanInTheLoopMiddleware von LangChain oder einem interrupt aus LangGraph.

Weitere Beispiele

Ein Modell und seine Eingaben finden

Modelle aufzulisten ist kostenlos. Mit model gibt das Tool die Eingabefelder und Preise dieses Modells zurück:

from langchain_popnow import PopNowListModels

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

Ein Bild mit einem gewählten Modell animieren

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

Sprachaufnahmen ohne Bestätigung für jede Zeile

Eine Sprachaufnahme kostet einen Bruchteil eines Cents, deshalb kann eine Pipeline kleine Angebote selbst bestätigen:

from langchain_popnow import PopNowSpeech

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

Jedes Modell per ID

PopNowCreateTask sendet das eigene input eines Modells, genau wie 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",
})

Jedes Tool läuft außerdem asynchron: await tool.ainvoke(...).

Preise

Modelle auflisten, Tasks abfragen und das Guthaben prüfen ist kostenlos. Generierungs-Tools berechnen den USD-Preis des Modells von deinem API-Guthaben: Ein Task reserviert beim Annehmen seinen angebotenen Preis und verrechnet den tatsächlichen Betrag, wenn er fertig ist. Tasks, die fehlschlagen oder ablaufen, kosten nichts.

popnow_list_models gibt die USD-Preise jedes Modells zurück. Den Preis jedes Modells findest du unter Modelle und auf seiner eigenen Modellseite; der KI-Preisindex listet sie ebenfalls auf. Wie Angebote, Reservierungen und Rückerstattungen funktionieren, steht unter Abrechnung und Angebote.

Häufige Fehler

Die vollständige Liste steht unter Fehler.

Funktioniert es mit LangGraph?

Ja. Die Tools sind Standard-LangChain-Tools, deshalb können create_react_agent, ToolNode und eigene LangGraph-Graphen sie aufrufen. Kombiniere sie mit einem LangGraph-interrupt, wenn ein Mensch jeden Preis bestätigen soll.

Kann ein Agent mein Guthaben ausgeben, ohne zu fragen?

Standardmäßig nicht. Ein kostenpflichtiges Tool, das ohne max_usd aufgerufen wird, liefert nur ein Angebot. Ausgaben ohne Bestätigung passieren nur, wenn du auto_approve_usd setzt; max_usd_per_call und die Ausgabelimits des Schlüssels gelten trotzdem.

Welche Modelle können die Tools verwenden?

Jedes Bild-, Video- oder Audiomodell im Katalog. Die Generierungs-Tools haben sinnvolle Standardwerte; übergib model, um ein anderes zu wählen, oder nutze PopNowCreateTask mit einer beliebigen Modell-ID. popnow_list_models listet die IDs direkt aus dem Agenten heraus auf.

Gibt es eine JavaScript-Version?

Für TypeScript und JavaScript nutze den Vercel-AI-SDK-Provider oder das JavaScript-SDK.

Verwandte Seiten