Zhiqian LLM API 연동

가격과 충전만 알고 싶다면

이 페이지는 프로그램에서 호출하는 개발자를 위한 것입니다. ZQAgent 안에서 대규모 모델만 사용한다면 Key를 신청할 필요도, 이 페이지를 볼 필요도 없습니다. Zhiqian LLM(가격과 충전)을 참고하세요.

Zhiqian LLM API는 OpenAI 호환 대규모 모델 게이트웨이입니다. Key 하나, 주소 하나로 DeepSeek, Qwen, Xiaomi MiMo 등 여러 상류 모델을 호출할 수 있으며, 공급자마다 따로 연동하거나 충전할 필요가 없습니다.

이미 OpenAI SDK를 쓰는 프로젝트라면 보통 base_url과 api_key 두 곳만 바꾸면 됩니다.

적합한 경우

자체 앱에 안정적인 모델 출구가 필요하고, 단일 공급자의 한도나 장애에 묶이고 싶지 않음
팀이 할당량을 공유하고 실제 사용량으로 정산하고 싶음(멤버마다 많은 Key를 나눠 주고 싶지 않음)
잔액, 소비 내역, 충전 기록을 조회해 원가 계산이나 외부 과금을 하려는 경우

빠른 시작

1. API Key 받기

사용자 센터에 가입하면 Zhiqian LLM API가 자동으로 개통되고 5위안 크레딧이 지급됩니다. 별도 신청이 필요 없습니다. 사용자 센터의 'Zhiqian LLM API' 페이지에서 다음을 할 수 있습니다:

Key 보기: 페이지는 기본으로 마스킹되며 필요할 때 전체 값을 표시
Key 재발급: 기존 Key는 즉시 무효. 노드 측 구성은 약 5초 후 갱신되므로 재발급 후 잠시 기다렸다가 테스트
셀프 충전: 위챗페이와 알리페이 지원

페이지에서 신청이 필요하다고 표시되면 안내에 따라 용도와 연락처를 적고, 개통 후 Key를 확인하세요.

Key는 sk-로 시작하는 문자열입니다. 반드시 시크릿 관리 시스템에 보관하고 코드 저장소나 프런트엔드 페이지에 쓰지 마세요.

2. 요청 한 번 보내기

bash

curl https://zqai-api.cd-zq.com/v1/chat/completions \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zq-standard",
    "messages": [{"role": "user", "content": "안녕하세요"}],
    "max_tokens": 128
  }'

3. OpenAI SDK 사용

PythonNode.js

python

from openai import OpenAI

client = OpenAI(
    base_url="https://zqai-api.cd-zq.com/v1",
    api_key="sk-내Key",
)

resp = client.chat.completions.create(
    model="zq-standard",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)

javascript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://zqai-api.cd-zq.com/v1',
  apiKey: process.env.ZQAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: 'zq-standard',
  messages: [{ role: 'user', content: '안녕하세요' }],
});
console.log(resp.choices[0].message.content);

접속 정보

항목	값
Base URL	`https://zqai-api.cd-zq.com/v1`
인증	`Authorization: Bearer <API Key>`
프로토콜	HTTPS, 스트리밍은 `text/event-stream`
OpenAPI 규격	openapi.yaml
요청 body 상한	32 MB(이미지·오디오를 base64로 인라인할 때 필요)

OpenAPI 규격은 Apifox, Postman, Swagger Editor에 바로 가져올 수 있고 클라이언트 SDK 생성에도 쓸 수 있습니다.

인터페이스

두 그룹으로 나뉘며, 같은 Key와 같은 잔액을 사용합니다:

그룹	용도	경로 접두사
모델 호출	대화 완성, OpenAI 호환	`/v1/chat/completions`, `/v1/models`
일반 API	OCR, 기업 정보 조회 등 모델이 아닌 인터페이스, 호출당 과금	`/v1/proxy/{slug}/...`

계정 조회와 자금 거래 내역은 두 그룹 모두에서 사용할 수 있습니다.

모델 목록

http

GET /v1/models

현재 Key에 사용 권한이 있는 모델 별칭만 반환합니다.

json

{
  "object": "list",
  "data": [
    { "id": "zq-standard", "object": "model", "created": 0, "owned_by": "zqai" }
  ]
}

채팅 완성

http

POST /v1/chat/completions

OpenAI의 chat/completions와 호환되며 일반적인 필드를 지원합니다: messages, stream, max_tokens, temperature, top_p, stop, tools, tool_choice, response_format. model에 이 서비스의 별칭을 넣으면 게이트웨이가 해당 상류로 자동 라우팅합니다.

스트리밍 호출:

bash

curl -N https://zqai-api.cd-zq.com/v1/chat/completions \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zq-standard",
    "messages": [{"role": "user", "content": "50자로 자기소개를 써 줘"}],
    "stream": true
  }'

스트리밍 응답은 OpenAI와 같으며 data: [DONE]으로 끝납니다.

계정 조회

같은 Key로 자신의 테넌트 데이터를 조회합니다. 추가 매개변수가 필요 없고 다른 사람의 데이터는 조회할 수 없습니다.

인터페이스	용도
`GET /v1/account/balance`	실시간 사용 가능 잔액, 보류 중 동결, 원장 잔액
`GET /v1/account/usage`	소비 요약. 일별 또는 모델별 집계 가능
`GET /v1/account/usage/records`	요청 단위 소비 내역
`GET /v1/account/recharges`	충전 횟수, 누적 충전액, 충전 기록

자금 흐름

bash

curl "https://zqai-api.cd-zq.com/v1/account/transactions?kind=refund" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

충전, 소비, 환불, 조정의 전체 흐름을 반환합니다. amount는 부호가 있고(입금 양수, 출금 음수) 기간 집계도 포함합니다. 대사나 세금계산서 발행에는 recharges보다 완전합니다.

bash

# 잔액
curl https://zqai-api.cd-zq.com/v1/account/balance \
  -H "Authorization: Bearer $ZQAI_API_KEY"

# 최근 7일 소비를 모델별로 집계
curl "https://zqai-api.cd-zq.com/v1/account/usage?group_by=model" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

# 최근 20건 소비 내역
curl "https://zqai-api.cd-zq.com/v1/account/usage/records?limit=20" \
  -H "Authorization: Bearer $ZQAI_API_KEY"

잔액 응답 예시:

json

{
  "object": "account.balance",
  "tenant_id": 1,
  "currency": "CNY",
  "available_micros": 12345678,
  "available": 12.345678,
  "reserved_micros": 0,
  "reserved": 0.0,
  "ledger_balance_micros": 12345678,
  "ledger_balance": 12.345678,
  "source": "redis",
  "as_of": "2026-10-20T12:00:00Z"
}

두 잔액 기준의 차이:

필드	의미	확인 시점
`available`	Redis 핫 원장. 보류 중 동결 차감 완료	"아직 요청을 보낼 수 있나" 판단
`ledger_balance`	PG 흐름 기준. 보류 중 동결 미포함	대사, 세금계산서

소비는 윈도 단위로 집계해 입장되므로 ledger_balance가 실시간 잔액보다 1~5분 늦을 수 있습니다. 이는 정상적인 결제 지연입니다.

금액 단위

응답은 *_micros와 위안을 함께 제공합니다. 프로그램 내 기장에는 마이크로 위안 정수를 사용하세요(1위안 = 1,000,000 마이크로 위안). 위안 필드는 표시 전용이며 합산에 쓰면 부동소수점 오차가 생깁니다.

일반 API 프록시

대화 모델 외에도 게이트웨이는 모델이 아닌 업스트림 인터페이스를 전달할 수 있습니다 — OCR, 기업 정보 조회, 음성 인식 등입니다. 같은 Key, 같은 잔액을 쓰며 청구서도 한곳에 모입니다.

파라미터 형식은 서비스에 따라 다릅니다

게이트웨이는 전달만 하고 프로토콜을 변환하지 않습니다. 어떤 서비스가 어떤 파라미터를 받고 어떤 구조를 반환하는지는 그 뒤에 어떤 업스트림이 연결됐는지에 달려 있습니다. 운영 담당자가 준 인터페이스 설명을 기준으로 하세요 — 아래 모든 예시의 {slug}와 요청 본문은 실제 서비스의 것으로 바꿔야 합니다.

사용 가능한 서비스 확인

bash

curl https://zqai-api.cd-zq.com/v1/api-services \
  -H "Authorization: Bearer $ZQAI_API_KEY"

json

{
  "object": "list",
  "data": [
    {
      "slug": "ocr",
      "name": "일반 OCR",
      "billing_mode": "per_call",
      "unit_price": 0.01,
      "allowed_methods": ["POST", "GET"]
    }
  ]
}

사용 권한이 있는 서비스만 반환됩니다. slug는 호출 주소의 해당 부분이고, unit_price는 호출 1회 가격(위안), billing_mode는 아래 과금 규칙을 참고하세요.

호출 방법

/v1/proxy/{slug}/ 뒤의 부분을 그대로 업스트림 경로에 연결합니다:

text

요청:      POST /v1/proxy/ocr/general?lang=zh
업스트림:  POST {업스트림 주소}/{운영 설정 경로}/general?lang=zh

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/general" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "iVBORw0KGgo..."}'

바이너리 응답은 base64로 변환하지 않고 바로 파일로 저장할 수 있습니다:

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/image" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -d '{"url": "https://example.com/a.jpg"}' \
  -o result.png

파일 업로드는 multipart도 가능하며, 게이트웨이는 원본 바이트 그대로 전달합니다:

bash

curl -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/file" \
  -H "Authorization: Bearer $ZQAI_API_KEY" \
  -F "file=@invoice.pdf"

모델 인터페이스와의 차이

항목	대화 모델	일반 API 프록시
경로	`/v1/chat/completions`	`/v1/proxy/{slug}/...`
요청 본문	고정된 OpenAI 형식	임의(JSON / 바이너리 / multipart)
응답	고정된 OpenAI 형식	그대로 반환(업스트림이 결정)
과금	token 기준	호출당
스트리밍	SSE 프레임 단위	그대로 전달(프레임 파싱 없음)

공통점: 같은 Key, 같은 잔액, 같은 속도 제한과 감사.

과금 규칙

모드	의미	차감 시점
`per_call`	호출당 고정 가격	호출 성공(2xx) 시 `unit_price` 차감
`cost_markup`	업스트림 원가에 가산	호출 성공 시 "원가 × (1 + 가산율)" 차감
`free`	과금 없음	사용량만 기록하고 잔액은 그대로

성공(2xx)에만 과금합니다. 업스트림 오류나 네트워크 실패는 차감되지 않습니다.
호출 전에 한도 한 번을 확보하며, 실패하면 전액 반환합니다.
잔액이 부족하면 바로 402를 반환하고, 업스트림을 호출한 뒤 실패하는 일은 없습니다.

주의 사항

당신의 Key는 업스트림으로 전달되지 않습니다. 게이트웨이는 Authorization, x-api-key, Cookie 같은 헤더를 제거하고 운영 설정의 업스트림 자격 증명으로 교체합니다. 따라서 업스트림이 보는 것은 플랫폼 계정이며 당신이 아닙니다.

메서드가 일치해야 합니다. 서비스에 설정된 메서드만 사용할 수 있고, 틀리면 400을 반환하며 오류 메시지에 허용된 메서드가 나열됩니다.

오류 코드는 업스트림이 아니라 게이트웨이의 것입니다. 업스트림이 4xx/5xx를 반환하면 게이트웨이는 일괄적으로 502(code: upstream_error)를 반환하고 원래 상태 코드는 전달하지 않습니다 — 업스트림의 계정 상태나 할당량 세부 정보를 노출하지 않기 위해서입니다.

문제가 생기면 요청 ID를 알려주세요. 모든 응답 헤더에는 성공과 실패 모두 x-request-id가 있습니다. 운영 담당자에게 보내면 이 호출에서 업스트림에 무슨 일이 있었는지 바로 확인할 수 있습니다:

bash

curl -i -X POST "https://zqai-api.cd-zq.com/v1/proxy/ocr/general" \
  -H "Authorization: Bearer $ZQAI_API_KEY" -d '{}' | grep -i x-request-id

응답 헤더는 필터링됩니다. 홉 바이 홉 헤더(connection, transfer-encoding 등)는 전달되지 않고 나머지는 그대로 유지됩니다. 게이트웨이가 자체적으로 두 개의 헤더를 추가합니다:

응답 헤더	의미
`x-request-id`	이번 호출의 요청 ID. 성공·실패 모두 있으며 문제 해결 시 운영 담당자에게 전달
`x-charge-micros`	이번 차감액(마이크로위안, 1위안 = 1,000,000). `free` 모드에서는 0

과금

실제 token 사용량으로 과금하며 선불입니다. 먼저 충전하고, 잔액이 부족하면 요청이 바로 402를 반환합니다.

가격은 모델별로 다릅니다. 자세히는 가격
스트리밍과 비스트리밍의 과금 기준은 동일
상류 장애나 요청 매개변수 오류는 과금 없음. 클라이언트가 중간에 끊으면 생성된 내용까지 과금
잔액 부족 시 대기열도 외상도 없으며 먼저 충전해야 함

사용자 센터의 'Zhiqian LLM API' 페이지에서 셀프 충전(위챗페이 / 알리페이)할 수 있고 반영 후 바로 사용할 수 있습니다.

오류 코드

모든 오류는 OpenAI 호환 형식입니다:

json

{
  "error": {
    "message": "잔액 부족",
    "type": "invalid_request_error",
    "param": null,
    "code": "insufficient_balance"
  }
}

HTTP	code	의미	대처
400	`invalid_request`	매개변수가 잘못됨	요청 수정
401	`invalid_api_key`	Key 누락, 무효, 만료, 중지	Key 확인
402	`insufficient_balance`	잔액 부족	충전. 재시도는 무의미
403	`forbidden`	테넌트 중지, 또는 Key에 해당 모델 권한 없음	운영 담당자에게 문의
404	`not_found`	모델 또는 경로 없음	모델 별칭 확인
429	—	속도 제한 도달	백오프 후 재시도
500	`internal_error`	서비스 내부 오류	나중에 재시도. 지속되면 문의
502	`upstream_error`	상류 장애	백오프 후 재시도
503	`capacity_exhausted`	모든 채널 포화 또는 서킷 브레이커	`Retry-After`에 따라 백오프

503에는 Retry-After 응답 헤더가 붙습니다. 지정된 시간만큼 기다렸다가 재시도하고 즉시 재시도하지 마세요.

자주 묻는 질문

Key를 잃어버리면? 사용자 센터의 'Zhiqian LLM API' 페이지에서 'Key 재발급'을 누르면 기존 Key가 즉시 무효가 됩니다. Key는 서버에 해시만 저장되어 원래 값을 복구할 수 없습니다.

Key를 여러 개 발급할 수 있나요? 현재 계정 하나에 Key 하나이며 같은 잔액을 공유합니다. 교체가 필요하면 'Key 재발급'을 사용하면 기존 Key가 즉시 무효가 됩니다.

공급자 장애를 직접 처리해야 하나요? 아니요. 게이트웨이에 주/대기 강등과 서킷 브레이커가 내장되어 있어 주 채널 실패 시 자동으로 대기 채널로 전환하고, 모든 채널을 쓸 수 없을 때만 503을 반환합니다. 클라이언트는 503의 백오프 재시도만 처리하면 됩니다.

이미지와 도구 호출을 지원하나요? 선택한 모델의 능력에 따릅니다. 요청에 tools나 이미지 내용이 있으면 게이트웨이는 이를 지원하는 채널로만 라우팅합니다. 사용 가능한 채널이 없으면 400을 반환하며 조용히 텍스트 전용으로 강등하지 않습니다.

동시성과 속도 제한은? Key별로 설정되며 기본은 테넌트 공유입니다. 명확한 고동시성 요구가 있으면 개통 시 알려 주세요. 시나리오에 맞춰 할당량을 설정합니다.

Zhiqian LLM API 연동 ​

적합한 경우 ​

빠른 시작 ​

1. API Key 받기 ​

2. 요청 한 번 보내기 ​

3. OpenAI SDK 사용 ​

접속 정보 ​

인터페이스 ​

모델 목록 ​

채팅 완성 ​

계정 조회 ​

자금 흐름 ​

일반 API 프록시 ​

사용 가능한 서비스 확인 ​

호출 방법 ​

모델 인터페이스와의 차이 ​

과금 규칙 ​

주의 사항 ​

과금 ​

오류 코드 ​

자주 묻는 질문 ​

관련 링크 ​

Zhiqian LLM API 연동

적합한 경우

빠른 시작

1. API Key 받기

2. 요청 한 번 보내기

3. OpenAI SDK 사용

접속 정보

인터페이스

모델 목록

채팅 완성

계정 조회

자금 흐름

일반 API 프록시

사용 가능한 서비스 확인

호출 방법

모델 인터페이스와의 차이

과금 규칙

주의 사항

과금

오류 코드

자주 묻는 질문

관련 링크