Outils LangChain et LangGraph

langchain-popnow donne aux agents LangChain et LangGraph des outils qui créent des images, des vidéos, des musiques et des voix avec les modèles PopNow, ainsi que des outils qui listent les modèles, récupèrent les tâches et consultent le solde API. Une seule clé API couvre tous les modèles, de Nano Banana et Seedream à MiniMax H3, Kling, Suno et Gemini TTS.

Chaque appel payant fait d’abord l’objet d’un devis en USD. Un outil payant appelé sans max_usd renvoie seulement le prix : rien n’est créé et rien n’est débité. Le paquet est open source sous licence MIT (GitHub) et repose sur le SDK Python officiel.

En un coup d’œil

Mise en place

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

Lorsqu’un agent appelle l’outil avec un ToolCall, l’outil renvoie un ToolMessage dont content est le résumé JSON ci-dessus et dont artifact est l’enregistrement complet de la tâche ou du devis PopNow.

Outils

PopNowToolkit().get_tools() renvoie les huit avec une configuration commune.

Les outils de génération acceptent les champs communs (prompt, aspect_ratio, resolution, duration_seconds, voice_id et ainsi de suite), un model facultatif pour choisir un autre modèle PopNow, et extra_input pour tout champ que popnow_list_models indique pour ce modèle. Les IDs de modèle suivent le schéma <maker>/<model>/<task> décrit dans Modèles.

Comment fonctionne la confirmation

Les tâches PopNow sont asynchrones : devis, création au prix confirmé, puis attente du résultat. Les outils suivent le même déroulement que le serveur MCP pour développeurs :

1. Devis. L’agent appelle un outil payant sans max_usd. L’outil demande un devis à PopNow et renvoie status: "needs_confirmation" avec cost_usd. Rien n’est créé ni bloqué.
2. Confirmation. L’agent montre le prix à l’utilisateur. Après accord, il rappelle l’outil avec les mêmes arguments, plus max_usd égal au cost_usd devisé.
3. Exécution. Si le devis en cours ne dépasse pas max_usd, la tâche est créée avec ce devis bloqué et l’outil attend le résultat. Si le prix a augmenté, l’outil renvoie un nouveau needs_confirmation et ne débite rien.

Les résultats contiennent des URLs de téléchargement signées, qui expirent, et une URI popnow://g/<task>/<n> qui n’expire pas et peut être passée à un autre outil PopNow, par exemple pour animer une image générée. Une longue vidéo peut encore tourner lorsque wait_timeout (600 secondes par défaut) est écoulé : l’outil renvoie alors status: "running" avec un task_id, et popnow_get_task récupère le résultat plus tard. Les tâches échouées ou expirées libèrent leur blocage et ne coûtent rien.

Garde-fous de dépense

Définissez ces options sur n’importe quel outil payant ou sur PopNowToolkit :

Les plafonds de dépense et la liste d’autorisation de modèles de la clé API, réglés dans la console API, s’appliquent aussi.

Utiliser avec un agent 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)

L’agent peut tourner sur n’importe quel modèle de chat pris en charge par LangChain, y compris les modèles de chat PopNow via le point de terminaison compatible OpenAI https://api.popnow.ai/v1.

Utiliser avec 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 fonctionne toujours dans LangGraph 1.x ; les nouveaux projets peuvent utiliser langchain.agents.create_agent, comme ci-dessus. Pour une étape d’approbation humaine stricte, combinez les outils avec HumanInTheLoopMiddleware de LangChain ou un interrupt de LangGraph.

Autres exemples

Trouver un modèle et ses entrées

Lister les modèles est gratuit. Avec model, l’outil renvoie les champs de saisie et les prix de ce modèle :

from langchain_popnow import PopNowListModels

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

Animer une image avec un modèle choisi

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

Voix off sans confirmation pour chaque ligne

Une voix off coûte une fraction de centime : un pipeline peut donc approuver seul les petits devis :

from langchain_popnow import PopNowSpeech

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

Tout modèle par ID

PopNowCreateTask envoie le input propre à un modèle, exactement comme dans Tâches :

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

Chaque outil fonctionne aussi de façon asynchrone : await tool.ainvoke(...).

Tarifs

Lister les modèles, lire les tâches et consulter le solde sont gratuits. Les outils de génération débitent le tarif USD du modèle sur votre solde API : une tâche bloque son prix devisé à son acceptation et règle le montant réel à la fin. Les tâches échouées ou expirées ne coûtent rien.

popnow_list_models renvoie les tarifs USD de chaque modèle. Le prix de chaque modèle figure sur Modèles et sur sa page dédiée ; l’indice des prix IA les liste aussi. Le fonctionnement des devis, des blocages et des remboursements est décrit dans Facturation et devis.

Erreurs courantes

La liste complète se trouve dans Erreurs.

Ça fonctionne avec LangGraph ?

Oui. Les outils sont des outils LangChain standard : create_react_agent, ToolNode et vos graphes LangGraph personnalisés peuvent donc les appeler. Associez-les à un interrupt LangGraph si une personne doit approuver chaque prix.

Un agent peut-il dépenser mon solde sans demander ?

Pas par défaut. Un outil payant appelé sans max_usd renvoie seulement un devis. Une dépense sans confirmation n’a lieu que si vous définissez auto_approve_usd ; max_usd_per_call et les plafonds de dépense de la clé restent appliqués.

Quels modèles les outils peuvent-ils utiliser ?

Tout modèle d’image, de vidéo ou d’audio du catalogue. Les outils de génération ont des valeurs par défaut raisonnables ; passez model pour en choisir un autre, ou utilisez PopNowCreateTask avec n’importe quel ID de modèle. popnow_list_models liste les IDs depuis l’agent lui-même.

Existe-t-il une version JavaScript ?

Pour TypeScript et JavaScript, utilisez le fournisseur Vercel AI SDK ou le SDK JavaScript.

Voir aussi