QNP API 문서

OpenAI 호환 프록시로, 제공자별로 키별 대체를 구성할 수 있습니다.

소개

QNP는 OpenAI 호환 API 게이트웨이입니다. 모든 OpenAI SDK를 기본 URL로 지정하면 기존 코드가 Anthropic, OpenAI, Google, Mistral, Groq 등으로 자동으로 라우팅됩니다 — 자동 폴백과 함께.

구성 가능한 폴백 — 키별로 제공자 순서를 설정하세요.
OpenAI SDK 호환 — 드롭인 교체, 코드 변경 불필요.
BYOK 또는 플랫폼 크레딧 — 자체 키를 가져오거나 종량제로 이용하세요.
지원되는 제공자 — OpenAI, Anthropic, Google, Mistral, Groq 등.
통합 사용량, 청구 및 모니터링.

프로덕션 기본 URL: {url}

채팅의 경우, 모델 이름 qnp 또는 qnp/auto는 폴백 체인의 첫 번째 모델로 해석됩니다. 그렇지 않으면 QNP는 의도 기반 기본값을 사용합니다. 폴백 순서는 여전히 적용됩니다.

빠른 시작 가이드

계정 생성

Google, Apple, Passkey 또는 이메일 매직 링크를 사용하여 qnp.ai/login에서 가입하세요. 하루에 50개의 요청을 포함하는 무료 티어를 받게 됩니다.

API 키 받기

이동하세요 대시보드 → API 키 그리고 새 키를 만드세요. 제공자 체인을 구성하세요. 키를 복사하세요 — 이 키는 다음으로 시작합니다: qnp- 그리고 한 번만 표시됩니다.

첫 번째 요청을 생성하세요

OpenAI 호환 SDK 또는 cURL을 사용하세요. 기본 URL과 API 키만 변경하세요 (아래 참조).

사용량 모니터링

요청 로그, 비용 및 지연 시간을 대시보드 → 로그 페이지에서 확인하세요. 분석을 위해 데이터를 CSV로 내보내세요.

cURL

curl -X POST "https://qnp.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello!"}]}'

인증

모든 API 요청은 QNP 키를 통한 인증이 필요합니다. 두 가지 헤더 형식이 지원됩니다:

Authorization: Bearer YOUR_KEY
# or
X-API-Key: YOUR_KEY

키 관리

키는 대시보드에서 생성되며 생성 시에만 표시됩니다.
각 키에는 자체 제공자 체인이 있습니다 — 어떤 제공자로 폴백할지 선택하세요.
키는 허용된 IP, 리퍼러, 모델 및 일일 예산으로 범위를 지정할 수 있습니다.
다운타임 없이 키를 로테이션하세요 — 이전 키는 유예 기간 동안 유효합니다.
손상된 경우 즉시 키를 폐기하세요 — 이전 키는 다음 호출 시 401을 반환합니다.
무료 티어: 최대 5개의 활성 키, 일일 1,000 요청.

키 범위 지정

제공자 체인 — 시도할 제공자와 순서.
허용된 IP — 키 사용을 특정 IP 주소 또는 CIDR로 제한.
허용된 리퍼러 — 키 사용을 특정 출처로 제한.
권한 — 키별로 채팅, 임베딩, 이미지 또는 오디오.
예산 — USD 단위로 일일 지출 한도 설정.
속도 제한 — 키별 맞춤 RPM/TPM 상한.

대체 구성

API 키별로 제공자 체인을 정의합니다. QNP는 하나가 성공적인 응답을 반환할 때까지 순서대로 각각을 시도합니다.

예시: OpenAI (기본) → Anthropic (대체 1) → Groq (대체 2). OpenAI가 5xx 오류를 반환하면 트래픽이 Anthropic으로 전환됩니다.

대시보드의 Keys → [your key] → Routing에서 대체를 구성합니다.

대체가 구성되지 않은 경우, 키는 플랫폼 크레딧을 사용합니다 — 계정에 청구됩니다.

채팅 완성

POST/v1/chat/completions

OpenAI 호환 채팅 엔드포인트입니다. 스트리밍, 함수 호출 및 비전 입력을 지원합니다.

cURL

curl -X POST "https://qnp.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello!"}]}'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://qnp.ai/api/v1",
    api_key="YOUR_KEY"
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",  # routes to your fallback chain
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Node.js (OpenAI SDK)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://qnp.ai/api/v1",
  apiKey: "YOUR_KEY",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini", // routes to your fallback chain
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

임베딩

POST/v1/embeddings

텍스트에 대한 벡터 임베딩을 생성합니다 — 검색, 클러스터링 및 RAG에 유용합니다.

cURL

curl -X POST "https://qnp.ai/api/v1/embeddings" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"The quick brown fox"}'

Python

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox"
)
print(response.data[0].embedding[:5])

이미지

POST/v1/images/generations

DALL-E 및 기타 이미지 모델을 통해 이미지를 생성합니다.

모델

GET/v1/models

API 키에 사용 가능한 모델을 나열합니다.

cURL

curl "https://qnp.ai/api/v1/models" \
  -H "Authorization: Bearer YOUR_KEY"

스트리밍

QNP는 채팅 완료를 위해 서버 전송 이벤트(SSE) 스트리밍을 지원합니다. 요청 본문에 "stream": true를 설정하세요. 응답은 OpenAI 형식의 data: 이벤트 스트림입니다.

각 SSE 이벤트에는 델타 내용이 포함된 JSON 청크가 있습니다. 스트림은 data: [DONE]로 끝납니다.

cURL

curl -X POST "https://qnp.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","stream":true,"messages":[{"role":"user","content":"Hello!"}]}'

Python

stream = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

모델 카탈로그

실시간 모델 카탈로그를 불러오는 중…

속도 제한

속도 제한은 API 키별로 적용됩니다. 기본 상한은 등급에 따라 다릅니다:

등급	일일 요청 수	RPM (기본값)	API 키
무료	일일 50회 요청	분당 10회 요청	5
프로	무제한	무제한	무제한

사용자 정의 키별 속도 제한(RPM, TPM)은 대시보드에서 구성할 수 있습니다.

속도 제한이 걸리면, API는 429 Too Many Requests와 함께 Retry-After 헤더를 반환합니다.

오류 코드

Errors follow OpenAI format: { error: { message, type, code } }

코드	의미	조치 방법
400	잘못된 요청	요청 본문 형식과 필수 필드를 확인하세요.
401	인증되지 않음	API 키가 유효하고 헤더에 포함되어 있는지 확인하세요.
402	크레딧 부족	대시보드에서 크레딧을 충전하거나 프로로 업그레이드하세요.
403	접근 금지	이 엔드포인트에 대한 키 권한이 없거나, IP/리퍼러가 차단되어 있습니다.
404	찾을 수 없음	엔드포인트 URL과 모델 이름을 확인하세요.
429	요청 제한	잠시 기다린 후 다시 시도하세요. Retry-After 헤더를 확인하세요. 더 높은 제한을 위해 등급을 업그레이드하세요.
500	내부 서버 오류	요청을 다시 시도하세요. 지속되면 지원팀에 문의하세요.
502	게이트웨이 오류	상위 제공자 오류입니다. 폴백 체인이 자동으로 다시 시도합니다.
503	서비스 사용 불가	제공자가 일시적으로 사용 불가입니다. 폴백 라우팅이 이를 처리합니다.

SDK 예제

OpenAI 호환 SDK를 사용하세요. 기본 URL과 QNP 키를 변경하기만 하면 됩니다.

Python

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="https://qnp.ai/api/v1",
    api_key="YOUR_KEY"
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",  # routes to your fallback chain
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Node.js

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://qnp.ai/api/v1",
  apiKey: "YOUR_KEY",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini", // routes to your fallback chain
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

LangChain

Python

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://qnp.ai/api/v1",
    api_key="YOUR_KEY",
    model="openai/gpt-4o-mini"  # routes to your fallback chain
)
response = llm.invoke("Hello!")
print(response.content)

Cline 설정

Cline은 AI 기반 VS Code 코딩 어시스턴트입니다. QNP는 Cline의 API 제공자로 작동합니다.

단계

Cline 설정을 열세요 (톱니바퀴 아이콘을 클릭하세요).
API 제공자를 OpenAI Compatible로 설정합니다.
Base URL: {url}.
API Key: QNP 키를 입력합니다 (qnp-로 시작).
모델: {model}을(를) 사용합니다 (또는 지원되는 다른 모델). QNP가 대체 체인에서 자동으로 선택하도록 하려면 qnp/auto를 전달하세요.

팁: 대시보드 → API 키에서 API 키 제공자 체인을 구성하세요. qnp/auto 모델은 해당 체인의 첫 번째 모델을 사용하며, 실패 시 자동으로 다음 모델을 시도합니다.

문제 해결

400 invalid_request_error: 키에 대체 체인에 최소 하나의 제공자가 포함되어 있는지 확인하세요. 대시보드 → 키 → 라우팅에서 Anthropic 또는 OpenAI를 추가하세요.
잘못된 API 키: 키가 qnp-로 시작하고 활성 상태인지 확인하세요.
Base URL: /v1로 끝나야 합니다 (후행 슬래시 없이).

설정 스크립트

설정 스크립트는 OpenClaw, Claude Code, Hermes Agent를 자동 감지하고 구성합니다. 통합된 대체 체인과 BYOK를 위해 QNP를 모델 제공자로 사용하세요.

설정 스크립트는 API 키와 Base URL을 대화형으로 입력받습니다.

bash

curl -fsSL https://qnp.ai/setup.sh | bash

스크립트의 동작

설치된 도구(OpenClaw, Claude Code, Hermes Agent)를 감지하고 각각에 대해 QNP를 제공자로 구성합니다.
모든 모델에 대해 input: ["text","image","audio","video"]을(를) 설정합니다.
변경 전에 백업을 생성합니다.