채팅 모델

PopNow API는 채팅 모델도 실행합니다. Claude, Gemini, DeepSeek, GLM, Grok, Kimi가 있습니다. 코드가 이미 쓰는 프로토콜인 OpenAI Chat Completions와 Responses, Anthropic Messages, Gemini generateContent로 호출하므로, 기본 URL만 바꾸면 공식 SDK를 그대로 쓸 수 있습니다. API 이미지·영상·오디오와 같은 sk-popnow- 키와 별도의 API USD 잔액을 씁니다. 초기 잔액은 $0이며 API billing에서 입금합니다. 웹사이트 크레딧으로는 결제할 수 없습니다.

채팅 호출은 동기식입니다. 같은 응답에서 답변(또는 스트림)을 받으며, 폴링할 작업은 없습니다.

한눈에 보기

첫 채팅 요청

curl https://api.popnow.ai/v1/chat/completions \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-5.5/chat",
    "messages": [
      { "role": "system", "content": "You are a concise, friendly assistant." },
      { "role": "user", "content": "Suggest three names for a kite shop by the sea." }
    ],
    "max_tokens": 512
  }'

응답은 표준 chat.completion 객체이며 choices[0].message.content와 usage를 담고 있습니다. X-PopNow-Task-Id 응답 헤더는 청구를 기록한 작업을 알려 줍니다.

OpenAI SDK

클라이언트가 https://api.popnow.ai/v1을 바라보게 하고 PopNow 키를 넘기세요. 그 밖에는 바꿀 것이 없습니다.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.popnow.ai/v1", api_key=os.environ["POPNOW_API_KEY"])

reply = client.chat.completions.create(
    model="anthropic/claude-haiku-5.5/chat",
    messages=[{"role": "user", "content": "Write a haiku about kites."}],
    max_tokens=200,
)
print(reply.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.popnow.ai/v1', apiKey: process.env.POPNOW_API_KEY });

const reply = await client.chat.completions.create({
  model: 'google/gemini-3.7-flash/chat',
  messages: [{ role: 'user', content: 'Write a haiku about kites.' }],
  max_tokens: 200,
});
console.log(reply.choices[0].message.content);

Responses API(client.responses.create)도 작동하며, 상태가 없는 형태로 씁니다. 매번 대화 전체를 input에 보내세요. previous_response_id를 보내면 400이 옵니다.

Anthropic SDK

Anthropic SDK는 /v1/messages를 직접 붙이므로, 기본 URL에는 /v1이 없습니다.

import os
import anthropic

client = anthropic.Anthropic(base_url="https://api.popnow.ai", api_key=os.environ["POPNOW_API_KEY"])

message = client.messages.create(
    model="anthropic/claude-sonnet-5.5/chat",
    max_tokens=512,
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(message.content[0].text)

이 엔드포인트는 Claude만이 아니라 모든 채팅 모델에서 동작합니다. 오류는 Anthropic의 {"type": "error", "error": {...}} 형식으로 옵니다.

Gemini generateContent

전체 모델 ID를 경로에 넣으세요. 모델 ID에는 슬래시가 들어갈 수 있습니다.

curl "https://api.popnow.ai/v1beta/models/google/gemini-3.7-flash/chat:generateContent" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "role": "user", "parts": [{ "text": "Name three colours of a sunset." }] }],
    "generationConfig": { "maxOutputTokens": 256 }
  }'

스트림을 받으려면 :streamGenerateContent?alt=sse를 쓰세요. 오류는 Google의 {"error": {"code", "message", "status"}} 형식으로 옵니다.

스트리밍

stream: true를 설정하고 Server-Sent Events를 읽으세요. Chat Completions에서는 모든 청크가 chat.completion.chunk이며, 스트림은 data: [DONE]으로 끝납니다. OpenAI와 마찬가지로 스트림에는 요청하지 않는 한 usage가 없습니다. stream_options: { "include_usage": true }를 설정하면 마지막 청크 하나에 usage가 오며, 이때 choices 배열은 비어 있습니다.

stream = client.chat.completions.create(
    model="anthropic/claude-haiku-5.5/chat",
    messages=[{"role": "user", "content": "Count from one to five."}],
    max_tokens=100,
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

도구, JSON 출력과 파라미터

각 모델은 받을 수 있는 요청 필드를 선언합니다. tools, tool_choice, response_format, temperature, reasoning_effort 등이 있습니다. 모델 표의 Parameters 열에 나와 있고, GET /v1/models는 이를 supported_parameters로 돌려줍니다.

• 모델이 받지 않는 샘플링 설정(temperature, top_p, frequency_penalty …)은 실패하지 않고 버려지며, X-PopNow-Ignored-Params 응답 헤더에 이름이 적힙니다.
• 모델의 허용 범위를 벗어난 값은 가장 가까운 허용 값으로 조정되며, X-PopNow-Adjusted-Params에 name=value 형식으로 보고됩니다.
• 모델이 선언하지 않은 다른 필드는 400과 code: unsupported_parameter를 돌려주며, param에 그 필드 이름이 나옵니다. 예를 들어 텍스트 전용 모델에 이미지 파트를 보내면 이렇게 됩니다.

모델과 가격

가격은 100만 토큰당 USD이며 입력과 출력을 따로 씁니다. 캐시된 입력은 캐시를 지원하는 모델에서 더 저렴합니다. 일부 모델은 요청이 긴 컨텍스트 기준을 넘으면 더 높은 요율을 받으며, 이는 모델 이름 아래에 표시됩니다.

같은 목록을 API에서도 가격, 컨텍스트 길이, 지원 파라미터와 함께 받을 수 있습니다.

curl "https://api.popnow.ai/v1/models?modality=text" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

채팅 요청의 과금 방식

1. 홀드. 요청이 접수되면 max_tokens와 입력으로 계산한, 가능한 최대 비용을 잔액에서 잡아 둡니다. max_tokens를 생략하면 모델이 낼 수 있는 최대 출력이 쓰이므로, 홀드를 작게 유지하려면 이 값을 설정하세요.
2. 청구. 답변이 끝나면 실제로 쓴 토큰만큼 USD로 냅니다. 요청당 최소 금액은 없습니다. 남은 홀드는 풀립니다.
3. 환불. 실패했거나 모델이 거절한 요청은 전액 환불됩니다.

홀드보다 잔액이 적거나 키의 지출 한도를 넘게 되면 모델로 아무것도 보내기 전에 402를 돌려줍니다. 정확한 청구액을 보려면 X-PopNow-Task-Id에 적힌 작업을 GET /api/v1/jobs/recordInfo로 읽으세요. costUsd는 표시와 회계 처리에 쓸 USD 십진수 문자열입니다. 기존 크레딧 필드가 함께 올 수도 있지만 USD 청구액을 정수 크레딧으로 반올림하지 마세요.

긴 답변과 오류

• 긴 비스트리밍 호출. 답변이 약 30초를 넘으면 먼저 200 상태와 X-PopNow-Keepalive: 1 헤더를 보내고, 15초마다 줄바꿈을 보낸 뒤, 마지막에 JSON 본문을 보냅니다. 그 이후에 실패하면 200 본문 안에 프로토콜의 일반적인 오류 객체로 전달되므로, 이 헤더가 있을 때는 error 키가 있는지 확인하세요. 스트리밍을 쓰면 이런 문제가 없습니다.
• 404 model_not_found. 모델 ID가 없습니다. 오류 메시지에 호출할 수 있는 가장 가까운 채팅 모델이 나옵니다.
• 400이고 param: model. 그 ID는 이미지, 영상, 오디오 모델입니다. 이 모델들은 작업으로 실행됩니다.
• 400이고 content_rejected. 모델 자체의 콘텐츠 정책이 요청을 거절했습니다. 청구되지 않습니다.
• 402. 홀드에 필요한 API USD가 부족하거나 키의 지출 한도에 걸렸습니다. API 결제를 보세요.

개인정보

요청은 작성한 그대로 모델에 전달되며, PopNow가 자체 시스템 프롬프트를 덧붙이지 않습니다. 각 모델의 자체 이용 정책이 적용됩니다. 메시지 본문은 청구가 확정된 뒤에는 보관하지 않습니다.

관련 문서