BytePlus ModelArk API 연결 안내
지역별 활성화, Bearer 인증, Chat 스트림과 처리 경계를 확인합니다.
리전, 모델 활성화와 인증 확인
BytePlus 국제 ModelArk Chat API를 OpenAI Python SDK로 일반 텍스트에 사용하는 안내입니다. 권한이 있는 계정, 대상 리전의 API 키와 그 리전에서 활성화한 실제 모델 ID가 필요합니다. 리전, 계정·프로젝트, 모델 버전, 호출 방식과 과금을 기록하세요. 목록에 모델이 보여도 계정 활성화나 잔액을 보장하지 않습니다.
예제는 API 키 Bearer 인증을 사용합니다. AK/SK는 별도 인증 경로이며 해당 문서에서 추론 엔드포인트 ID와 서명 요건을 확인해야 합니다. AccessKey를 이 예제의 API 키로 대신 넣지 마세요. 사용자 지정 추론 엔드포인트도 ID와 리전을 따로 확인합니다. Coding Plan 설정이 운영 백엔드의 인증·과금을 자동으로 대신하지는 않습니다.
리전 주소는 고정 데이터 위치 보장이 아닙니다
AP Base URL은 https://ark.ap-southeast.bytepluses.com/api/v3이며 공식 지역은 Johor, ap-southeast-1입니다. EU는 https://ark.eu-west.bytepluses.com/api/v3, Dublin, eu-west-1입니다. 호스트에 southeast가 있다는 이유로 AP를 싱가포르 모델 호스팅이라고 설명하지 마세요.
키, 모델 활성화와 추론 엔드포인트는 리전별로 분리됩니다. 콘솔도 대상 리전으로 바꾸어 확인하세요. 한편 지역 문서는 보통 해당 리전을 우선하되 AP와 EU 사이를 포함한 다른 리전으로 분산될 수 있다고 설명합니다. 어느 호스트를 골랐다는 사실만으로 엄격한 리전 내 처리를 보장할 수 없습니다. 제한이 있다면 적합한 계약·구성을 먼저 확인하고 자동 대체로 경계를 넘지 마세요.
설치와 자리표시자 설정
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai
ARK_API_KEY는 승인된 서버 환경에서 안전하게 주입합니다. 예시는 AP 형식이며 실제 리전으로 바꾸고 다른 리전의 키와 섞지 마세요. Chat, 일반 텍스트와 max_tokens 지원을 확인하고 활성화한 ID를 입력합니다.
export ARK_BASE_URL='https://ark.ap-southeast.bytepluses.com/api/v3'
export ARK_MODEL='YOUR-ACTIVATED-TEXT-MODEL-ID'
최소 비스트리밍 호출
다음을 modelark_chat.py로 저장하고 권한·비용을 확인한 후 python modelark_chat.py를 실행하세요. SDK는 Base URL에 /chat/completions를 붙입니다. /openai/v1이나 관리 API로 바꾸지 마세요. 출력128, 제한 시간30초와 자동 재시도0은 예제 설정이지 서비스 용량이나 응답 보장이 아닙니다.
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["ARK_BASE_URL"],
api_key=os.environ["ARK_API_KEY"],
timeout=30.0,
max_retries=0,
)
request = {
"model": os.environ["ARK_MODEL"],
"messages": [{"role": "user", "content": "Reply with one short greeting."}],
"max_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print("finish_reason:", answer.choices[0].finish_reason)
print(answer.usage.model_dump() if answer.usage else "usage unavailable")
반환 모델, finish reason과 usage를 확인한 뒤 답변이 테스트 목적에 맞는지 평가하세요. 잘림과 필터링은 정상 완료와 구분해야 합니다. HTTP200만으로 품질, 과금 귀속이나 지역 약정 검수가 끝난 것은 아닙니다.
텍스트와 상태를 따로 파싱하기
스트리밍 지원 모델이라면 비스트리밍 호출을 다음으로 바꾸세요. Chat은 SSE와 delta.content를 사용합니다. 추론은 reasoning_content, 도구는 별도 증분 구조일 수 있으므로 모두 사용자 답변에 합치면 안 됩니다. Responses에는 다른 파서가 필요합니다.
usage = None
finish_reason = None
with client.chat.completions.create(**request, stream=True) as events:
for part in events:
if part.usage is not None:
usage = part.usage
if not part.choices:
continue
choice = part.choices[0]
if choice.delta.content:
print(choice.delta.content, end="", flush=True)
if choice.finish_reason is not None:
finish_reason = choice.finish_reason
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")
인덱스 전에 choices를 확인하고 usage가 있으면 따로 저장합니다. 일부 스트림에는 usage가 없으며 예제는 공통 사용량 옵션을 가정하지 않습니다. 현재 모델 API를 확인하세요. 미확인은 요금0이 아닙니다. finish reason 뒤의 필요한 프레임도 읽고 중단은 미완료로 기록하며 상태 확인 후 재시도를 결정합니다.
오류 조사와 출시 확인
- 인증·권한: 키 출처, 리전, 프로젝트 권한과 모델 활성화를 점검하고 인증 정보를 공유하지 않습니다.
- 404·자원 없음: Base URL, 모델 또는 사용자 지정 엔드포인트 ID를 확인해 리전 혼동을 피합니다.
- 매개변수: 짧은 텍스트부터 시작해 지원하는 출력, 추론과 도구 설정을 하나씩 추가합니다.
- 제한·용량 부족: 할당량, 동시 실행과 계정 상태를 점검하고 대기 안내에 따라 제한적으로 재시도합니다. 무작정 리전을 바꾸지 마세요.
- 시간 초과/5xx: 민감 정보를 뺀 요청 ID, 시간, 부분 출력과 종료 상태를 기록하고 외부 작업 중복을 막습니다.
실제 서비스 조건에서 보관, 로그, 국경 간 처리와 삭제를 확인하세요. SDK 호환이 무보관이나 특정 관할권 요건 충족을 의미하지 않습니다. 모델, 입력·출력, 캐시, 배포, 재시도와 추가 서비스 비용을 청구와 대조합니다. 출력, 동시 실행과 전체 작업 시간을 제한하고 잘림, 중단, 접근 거부와 사용량 누락을 검수하세요.
예제는 오프라인 구문 및 합성 스트림 검사만 거쳤습니다. 키 읽기, 모델 활성화나 실제 서비스 호출은 하지 않았습니다. 가용성, 품질과 청구는 승인된 환경에서 확인해야 합니다.
공식 자료
확인일: 2026-10-17. 공개 지역·스트리밍 본문을 확인했으며 사용 전 현재 설정을 재확인하세요.