OpenRouter API 프로덕션 체크리스트

API 호환성 및 엔드포인트 확인

신뢰할 수 있는 통합을 위해 표준 OpenAI 호환 엔드포인트를 사용하세요.

주요 엔드포인트는 POST /v1/chat/completions. 이는 채팅 기록을 위한 텍스트 생성을 처리합니다. 두 번째 엔드포인트는 GET /v1/models, 사용 가능한 모델을 나열합니다. 텍스트 전용 작업에는 임베딩이나 이미지 생성 엔드포인트가 필요하지 않습니다. 많은 개발자가 복잡한 라우팅 레이어가 필요하다고 가정합니다. OpenRouter는 단일 진입점을 노출하여 이를 단순화합니다. 모델 ID와 시스템 프롬프트가 포함된 JSON 페이로드를 보냅니다. 서비스는 콘텐츠와 사용량 데이터가 포함된 구조화된 JSON을 반환합니다. 이 디자인은 공식 OpenAI SDK 기대치와 일치합니다. 클라이언트 코드를 변경하지 않고 모델을 교환할 수 있습니다. 구성의 모델 ID만 업데이트하면 됩니다. 클라이언트가 최신 JSON 스키마를 지원하는지 확인하세요. 이전 버전은 새 매개변수를 거부할 수 있습니다. 프로덕션에 배포하기 전에 연결을 테스트하세요. 응답 형식이 파서와 일치하는지 확인하세요.

인증 및 키 구성

생성 직후 API 키를 환경 변수에 즉시 보안하세요.

제공자 대시보드를 통해 키를 생성하세요. 안전한 곳에 저장하세요. 소스 저장소에 하드코딩하지 마세요. 다음을 통해 전달하세요. Authorization: Bearer <key> header. 각 키는 특정 계정에 연결됩니다. 누출이 의심될 경우 키를 교체할 수 있습니다. 일부 제공업체는 계정당 여러 키를 허용합니다. 이를 통해 개발 및 프로덕션 트래픽을 분리할 수 있습니다. 키별 사용량을 모니터링하여 이상 징후를 감지하세요. 사용하지 않는 키는 정기적으로 무효화하세요. 임시 스크립트에는 수명이 짧은 키를 사용하세요. 이는 침해 시 영향 범위를 줄입니다. SDK 버전이 Bearer 토큰 인증을 지원하는지 확인하세요. 이전 라이브러리는 다른 헤더 형식을 요구할 수 있습니다. 특정 SDK의 문서를 확인하세요. 키에 충분한 잔액이 있는지 확인하세요. 만료된 키는 401 오류를 반환합니다. 잔액이 0인 키는 402 오류를 반환합니다. 로직에서 이 두 상태를 구분하세요.

스트리밍 및 토큰 사용량 처리

낮은 지연 시간과 실시간 사용자 피드백을 위해 스트리밍을 활성화하세요.

設定 stream: true 요청 페이로드에 포함됩니다. 서버는 일련의 서버 전송 이벤트(SSE)를 전송합니다. 각 이벤트는 텍스트의 부분 청크를 포함합니다. 전체 응답을 구성하려면 이러한 청크를 조립해야 합니다. 마지막 청크에는 종종 토큰 사용량 통계가 포함됩니다. 이를 통해 실시간으로 비용을 추적할 수 있습니다. 스트리밍 없이 전체 응답을 기다려야 하므로 지각된 지연 시간이 크게 증가합니다. 스트리밍은 채팅 인터페이스에 필수적입니다. 이는 반응하는 듯한 타이핑 효과를 생성합니다. 스트리밍 중 오류 처리에 주의하세요. 연결이 끊어지면 현재 청크를 잃게 됩니다. 재연결 로직은 대화 상태를 보존해야 합니다. 일부 SDK는 스트리밍을 자동으로 처리합니다. 다른 SDK은 수동 이벤트 리스너가 필요합니다. 아키텍처에 맞는 접근 방식을 선택하세요. 파서가 불완전한 JSON 청크를 처리하는지 확인하세요. 각 이벤트가 완전한 객체라고 가정하지 마세요. 유효한 구조를 얻을 때까지 데이터를 버퍼링하세요.

속도 제한 및 동시성 모니터링

분당 요청 수를 추적하여 서비스 중단을 방지하세요.

OpenRouter는 API 키당 엄격한 속도 제한을 적용합니다. 이 제한을 초과하면 429 Too Many Requests 오류가 발생합니다. 재시도 로직에 지수 백오프(exponential backoff)를 구현해야 합니다. 동시 요청도 제한에 카운트됩니다. 남은 쿼터에 대한 응답 헤드를 확인하세요. 일부 제공업체는 이러한 헤드를 직접 노출합니다. 다른 제공업체는 오류를 통해 제한을 추론해야 합니다. 높은 동시성은 연결 풀을 고갈시킬 수 있습니다. 클라이언트가 연결을 효율적으로 관리하도록 하세요. 오버헤드를 줄이기 위해 연결 풀링을 사용하세요. 피크 부하 동안 대기열 깊이를 모니터링하세요. 제한에 도달하면 재시도 전에 기다리세요. 번개 떼 현상을 피하기 위해 대기 시간을 무작위로 조정하세요. 디버깅을 위해 모든 속도 제한 이벤트를 로깅하세요. 이는 사용 패턴을 식별하는 데 도움이 됩니다. 이러한 로그를 기반으로 동시성 설정을 조정하세요. 단일 키가 무제한 트래픽을 처리할 수 있다고 가정하지 마세요. 필요한 경우 여러 키에 부하를 분산하세요. 이는 신중한 상태 관리가 필요합니다. 필요한 경우 각 키가 자체 컨텍스트를 유지하도록 하세요.

암호화폐 청구 및 충전 관리

월 구독료 없이 토큰 사용량을 커버하기 위해 선불 크레딧을 사용하세요.

암호화폐로 계정에 충전하세요. 지원되는 네트워크에는 TRC20의 USDT와 Base의 USDC가 포함됩니다. 최소 충전 금액은 $20부터 시작됩니다. 큰 금액에는 보너스가 적용됩니다. $50 충전 시 5%, $100 충전 시 10%, $200 충전 시 15%의 추가 크레딧을 받습니다. 크레딧은 만료되지 않습니다. 이는 장기 프로젝트에 이상적입니다. 실제 사용된 토큰에 대해서만 비용을 지불합니다. 오류 및 거부는 무료입니다. 이는 예상치 못한 비용으로부터 예산을 보호합니다. 신규 계정에는 테스트용 $0.50 크레딧이 제공됩니다. 표준 구매에 대한 환불은 제공되지 않습니다. 중복 청구는 지원을 통해 수정됩니다. 지갑이 필요한 네트워크를 지원하는지 확인하세요. 전송 전에 계약 주소가 올바른지 확인하세요. 잘못된 네트워크를 사용하면 자금이 손실될 수 있습니다. 잔액을 정기적으로 확인하세요. 낮은 잔액은 서비스 중단으로 이어질 수 있습니다. 가능하면 자동 충전 기능을 사용하세요. 이는 중요한 작업의 지속적인 가용성을 보장합니다.

콘텐츠 필터 및 거부 테스트

모델이 무방비 프롬프트와 함께 예상대로 동작하는지 확인하세요.

Uncensored 모델은 여전히 하드 리밋을 적용할 수 있습니다. 특정 콘텐츠 유형의 제한 사항을 확인하십시오. 알려진 트리거 구문으로 테스트하십시오. 모델이 적절하게 응답하는지 확인하십시오. 일부 제공업체는 법적 이유로 필터를 유지합니다. 민감한 데이터에 모델을 의존하기 전에 이러한 사항을 확인하십시오. 도메인의 경계 사례를 테스트하십시오. 일반적으로 거부를 트리거하는 프롬프트를 보내십시오. 응답 형식을 관찰하십시오. 거부 이유를 반환합니까? 아니면 콘텐츠를 조용히 생성합니까? 통합 테스트에 이러한 동작을 문서화하십시오. 이는 프로덕션에서의 놀라움을 방지합니다. 모델의 동작이 변경되면 테스트를 업데이트하십시오. 팀에 중요한 변경 사항을 알리십시오. 일관성은 사용자 신뢰의 핵심입니다. 애플리케이션이 거부를 우아하게 처리하도록 보장하십시오. 모든 응답이 유효하다고 가정하지 마십시오. 출력 구조를 검증하십시오. 환각이나 포맷 오류를 확인하십시오. 이는 신뢰할 수 있는 사용자 경험을 보장합니다.

무료 요청에 대한 오류 처리 구현

원활한 사용자 경험을 유지하기 위해 오류를 우아하게 처리하세요.

네트워크 오류, 시간 초과 및 서버 오류가 발생할 수 있습니다. 지수 백오프와 함께 재시도 로직을 구현하세요. 일시적 오류와 영구적 오류를 구분하세요. 429 오류는 일시적입니다. 기다렸다가 재시도하세요. 400 오류는 영구적입니다. 입력 데이터를 확인하세요. 500 오류는 서버 측 오류입니다. 주의하여 재시도하세요. 디버깅을 위해 모든 오류를 로깅하세요. 요청 페이로드와 응답 본문을 포함하세요. 이는 문제 재현을 빠르게 도와줍니다. 사용자에게 원본 오류를 노출하지 마세요. 사용자 친화적인 메시지로 포맷팅하세요. 스트리밍 오류를 신중하게 처리하세요. 이벤트 스트림에서 연결을 해제하세요. 리소스를 정리하세요. 애플리케이션이 메모리 누수가 발생하지 않도록 하세요. 오류 시나리오를 철저히 테스트하세요. 네트워크 단절을 시뮬레이션하세요. 서버 시간 초과를 시뮬레이션하세요. 복구 로직이 작동하는지 확인하세요. 이는 열악한 조건에서도 신뢰성을 보장합니다.

JSON 모드와 도구 호출로 확장하세요

신뢰할 수 있는 데이터 추출 및 함수 실행을 위해 구조화된 출력을 사용하세요.

다음과 같이 설정하여 JSON 모드를 활성화하세요. response_format: {type: "json_object"}. 이는 모델이 유효한 JSON을 출력하도록 강제합니다. 데이터 구문 분석이나 구성 생성에 사용하세요. 도구 호출은 모델이 함수를 실행할 수 있게 합니다. 요청 페이로드에 도구를 정의하세요. 모델이 언제 호출할지 결정합니다. 결과를 모델에 다시 전달하세요. 모델은 출력 기반으로 최종 응답을 생성할 수 있습니다. 이는 복잡한 작업을 위한 루프를 만듭니다. 도구 정의가 명확해야 합니다. 모호한 도구는 잘못된 호출을 초래합니다. 구문 분석 전에 JSON 출력을 검증하세요. 이는 코드에서 런타임 오류를 방지합니다. 데이터 추출 작업에 도구 호출을 사용하세요. 정확도가 크게 향상됩니다. 다양한 입력 형식으로 테스트하세요. 모델이 예외 케이스를 처리하는지 확인하세요. 팀을 위해 사용 가능한 도구를 문서화하세요. 이는 프로젝트 전반에 걸쳐 일관된 사용을 보장합니다.

검토 프라이버시 및 데이터 사용 정책

제공자가 데이터를 어떻게 저장하고 사용하는지 이해하기.

데이터 보존 관련 개인정보 처리방침을 확인하세요. 일부 제공업체는 학습 목적으로 데이터를 사용하기도 합니다. 다른 곳은 데이터를 비공개로 유지합니다. 모델 개선에 데이터가 사용되지 않도록 하세요. 암호화 표준을 확인하세요. 데이터는 전송 중과 저장 시 모두 암호화되어야 합니다. 로그가 저장되는지 확인하세요. 로그에는 프롬프트가 포함될 수 있습니다. 이러한 로그가 안전한지 확인하세요. 서비스 약관에서 책임 한계 조항을 검토하세요. 생성된 콘텐츠의 소유권을 이해하세요. 일부 제공업체는 출력물에 대한 권리를 주장하기도 합니다. 이는 귀사의 요구 사항과 일치해야 합니다. 더 이상 서비스를 사용하지 않을 경우 계정을 삭제하세요. 데이터가 삭제되었는지 확인하세요. 우려 사항이 있으면 지원팀에 문의하세요. 감사 목적으로 개인정보 설정을 문서화하세요. 이는 내부 정책의 준수를 보장합니다.