LangChain 및 LangGraph 도구

langchain-popnow는 LangChain과 LangGraph 에이전트에 PopNow 모델로 이미지, 영상, 음악, 음성을 만드는 도구를 제공하며, 모델 목록, 작업 조회, API 잔액 확인 도구도 함께 제공합니다. API 키 하나로 Nano Banana와 Seedream부터 MiniMax H3, Kling, Suno, Gemini TTS까지 모든 모델을 쓸 수 있습니다.

모든 유료 호출은 먼저 USD로 견적을 받습니다. max_usd 없이 호출한 유료 도구는 가격만 반환합니다. 아무것도 만들지 않고 아무것도 청구하지 않습니다. 이 패키지는 MIT 라이선스의 오픈소스이며(GitHub), 공식 Python SDK 위에 만들어졌습니다.

한눈에 보기

설정

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 등)를 받습니다. 다른 PopNow 모델을 고르려면 model을, popnow_list_models가 그 모델에 대해 나열한 필드를 넣으려면 extra_input을 쓸 수 있습니다. 모델 ID는 모델에 설명된 <maker>/<model>/<task> 형식을 따릅니다.

USD 견적과 승인

PopNow 작업은 비동기입니다. 견적을 받고, 승인된 가격으로 만들고, 결과를 기다립니다. 도구는 개발자 MCP 서버와 같은 흐름을 따릅니다:

1. 견적. 에이전트가 max_usd 없이 유료 도구를 호출합니다. 도구는 PopNow에 견적을 요청하고 status: "needs_confirmation"과 cost_usd를 반환합니다. 이 시점에는 아무것도 만들거나 잡아두지 않습니다.
2. 승인. 에이전트가 사용자에게 가격을 보여줍니다. 승인되면 같은 인자에 견적된 cost_usd를 max_usd로 붙여 도구를 다시 호출합니다.
3. 실행. 현재 견적이 max_usd 이내이면, 그 견적을 잠근 채 작업을 만들고 도구가 결과를 기다립니다. 가격이 올랐다면 도구는 새 needs_confirmation을 반환하고 아무것도 청구하지 않습니다.

결과에는 만료되는 서명된 다운로드 URL과, 만료되지 않으며 popnow://g/<task>/<n> 형식의 URI가 들어 있습니다. 이 URI는 다른 PopNow 도구에 넘길 수 있습니다. 예를 들어 생성한 이미지를 움직이게 할 때 씁니다. 긴 영상은 wait_timeout(기본 600초)이 지나도 아직 실행 중일 수 있습니다. 그때 도구는 task_id와 함께 status: "running"을 반환하고, 나중에 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이 지원하는 모든 채팅 모델에서 실행할 수 있습니다. OpenAI 호환 엔드포인트 https://api.popnow.ai/v1을 통한 PopNow 채팅 모델도 포함됩니다.

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를 쓸 수 있습니다. 사람이 반드시 승인해야 하는 단계가 필요하면, 도구를 LangChain의 HumanInTheLoopMiddleware나 LangGraph의 interrupt와 함께 사용하세요.

더 많은 예제

모델과 입력 찾기

모델 목록 조회는 무료입니다. 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",
})

줄마다 승인 없이 내레이션 만들기

내레이션은 1센트의 일부만 들기 때문에, 파이프라인이 작은 견적은 스스로 승인할 수 있습니다:

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 가격 지수에서도 볼 수 있습니다. 견적, 홀드, 환불 방식은 결제와 견적을 참고하세요.

자주 나는 오류

전체 목록은 오류에 있습니다.

LangGraph에서도 작동하나요?

네. 도구는 표준 LangChain 도구이므로 create_react_agent, ToolNode, 직접 만든 LangGraph 그래프에서 모두 호출할 수 있습니다. 사람이 가격마다 승인해야 한다면 LangGraph의 interrupt와 함께 쓰세요.

에이전트가 물어보지 않고 잔액을 쓸 수 있나요?

기본값으로는 그럴 수 없습니다. max_usd 없이 호출한 유료 도구는 견적만 반환합니다. 승인 없이 지출되는 경우는 auto_approve_usd를 설정했을 때뿐이며, 이때도 max_usd_per_call과 키의 지출 한도는 계속 적용됩니다.

도구는 어떤 모델을 쓸 수 있나요?

카탈로그에 있는 이미지, 영상, 오디오 모델이면 모두 가능합니다. 생성 도구에는 적당한 기본값이 있으며, 다른 모델을 쓰려면 model을 넘기거나 PopNowCreateTask에 원하는 모델 ID를 넣으면 됩니다. popnow_list_models로 에이전트 안에서 ID를 확인할 수도 있습니다.

JavaScript 버전이 있나요?

TypeScript와 JavaScript에서는 Vercel AI SDK 제공자 또는 JavaScript SDK를 사용하세요.

관련 문서