개발자를 위한 Codex API 키 설명

API 키 형식 이해

codex api key를 제공하는 서비스에 가입하면 고유한 영숫자 문자열을 받게 됩니다. 이 키는 백엔드로 보내지는 모든 요청에 대한 인증 자격 증명으로 작동합니다. 형식은 일반적으로 sk-... 또는 유사한 접두사와 같은 표준 패턴을 따르지만, 제공업체의 구현에 따라 다릅니다. 그러나 독립적인 프록시를 사용 중이므로 정확한 접두사는 다를 수 있습니다. 중요한 것은 형식 자체가 아니라 키가 Bearer <your_key>로 HTTP Authorization 헤더에 올바르게 전달되는지 확인하는 것입니다.

API 키는 특정 계정과 사용량 등급에 연결됩니다. 일부 서비스는 서로 다른 환경(dev vs. prod)에 대해 여러 키를 생성하는 것과 달리, 당사 설정은 간단합니다: 하나의 계정, 하나의 키. 키를 분실하거나 도용된 것으로 의심되면 대시보드에서 즉시 재생성할 수 있습니다. 이렇게 하면 이전 키가 즉시 무효화되어 무단 접근이 지속되지 않습니다. 키를 교체할 때마다 환경 변수나 구성 파일을 업데이트해야 합니다.

보안 모범 사례

• 키를 소스 코드가 아닌 환경 변수에 저장하세요.
• codex api key을(를) 공개 저장소에 커밋하지 마세요.
• 노출이 의심될 경우 재생성 기능을 사용하세요.

일반적인 오류: 401 Unauthorized

401 Unauthorized 오류는 새 API 키를 통합할 때 가장 흔한 문제입니다. 이는 서버가 인증 정보를 거부했음을 의미합니다. claude code proxy 또는 모든 OpenAI 호환 엔드포인트의 맥락에서 이는 키가 누락되었거나, 잘못되었거나, 만료되었음을 거의 항상 의미합니다.

문제 해결을 위해 먼저 제공된 대로 키를 정확히 복사했는지 확인하세요. 키는 종종 대소문자를 구분하며, 잘못 복사하면 공백이 포함될 수 있습니다. 지역 또는 서비스 등급에 맞는 올바른 기본 URL을 사용하고 있는지 확인하세요. 최근에 키를 재생성했다면 클라이언트가 새 값을 사용하고 있는지 확인하세요. 401 오류는 사용량 잔액이나 속도 제한과 관련이 없으며, 순수한 인증 실패입니다.

해결을 위한 체크리스트

1. API 키 문자열이 대시보드와 정확히 일치하는지 확인하세요.
2. Verify the Authorization header format: Authorization: Bearer YOUR_KEY.
3. 계정 유형에 맞는 기본 URL이 올바른지 확인하세요.
4. 복사-붙여넣기 중에 불필요한 공백이 추가되지 않았는지 확인하세요.

속도 제한 초과: 429 오류

허용된 요청 볼륨을 초과하면 API는 429 Too Many Requests 오류를 반환합니다. 당사 서비스의 경우 키당 분당 300개 요청으로 제한이 설정됩니다. 이 제한은 공정한 사용과 모든 사용자를 위한 낮은 지연 시간을 보장하기 위해 적용됩니다. 고용량 코딩 세션을 실행하는 경우 코드가 여러 내부 요청을 트리거하는 경우 특히 이 제한에 빠르게 도달할 수 있습니다.

429 오류가 발생하면 응답에는 일반적으로 재시도 전에 대기해야 하는 초수를 나타내는 Retry-After 헤더가 포함됩니다. 클라이언트 코드에서 지수 백오프를 구현하는 것이 이러한 오류를 안정적으로 처리하는 표준 방법입니다. 즉시 재시도하는 대신 짧은 기간 동안 대기한 후, 후속 재시도마다 대기 시간을 두 배로 늘리십시오. 이렇게 하면 한도 재설정 동안 애플리케이션이 서버에 요청을 폭격하는 것을 방지할 수 있습니다.

속도 제한은 계정당이 아닌 키당 적용된다는 점에 유의하세요. 여러 장치나 프로세스가 동일한 키를 사용하는 경우 300 requests/minute 예산을 공유합니다. 더 높은 총 처리량이 필요한 경우 서로 다른 환경에 대해 별도의 키를 사용하는 것을 고려하세요.

기본 URL 올바르게 구성하기

베이스 URL은 모든 API 통합의 기초입니다. OpenAI 호환 서비스의 경우 베이스 URL은 요청이 전송되는 위치를 결정합니다. 저희 베이스 URL은 https://api.claudecodeapikey.com/v1입니다. 이 URL은 요청을 수행하기 전에 클라이언트 라이브러리 또는 SDK에 구성해야 합니다. 잘못된 베이스 URL을 사용하면 연결 오류 또는 예기치 않은 응답을 받게 됩니다.

많은 개발자가 Python, Node.js 또는 기타 언어용 공식 OpenAI SDK를 사용합니다. 저희 프록시로 전환하려면 베이스 URL 구성을 업데이트하기만 하면 됩니다. 예를 들어 Python에서는 base_url='https://api.claudecodeapikey.com/v1'를 설정할 수 있습니다. 프로토콜(https)과 경로(/v1)가 올바른지 확인하십시오. /v1 경로를 생략하면 404 오류가 발생하는 일반적인 실수입니다.

클라이언트가 올바른 엔드포인트로 요청을 보내는지 항상 확인하십시오. 네트워크 로그를 확인하거나 curl과 같은 도구를 사용하여 연결을 테스트하여 이를 수행할 수 있습니다. 베이스 URL에 대한 성공적인 연결은 구성이 올바르다는 것을 확인해 줍니다.

스트리밍 응답 처리

스트리밍 응답은 전체 응답이 완료되기를 기다리는 대신 API 응답의 일부를 생성되는 대로 받을 수 있게 합니다. 이는 코드 스니펫을 실시간으로 표시하는 코딩 에이전트에 중요합니다. 당사 API는 서버 전송 이벤트(SSE)를 통해 스트리밍을 지원합니다. 클라이언트에서 스트리밍을 활성화하면 부분 응답을 포함하는 청크의 스트림을 받게 됩니다.

스트리밍을 활성화하려면 요청에서 stream 매개변수를 true로 설정하십시오. 클라이언트 라이브러리는 SSE 프로토콜을 자동으로 처리합니다. 각 청크가 도착할 때 처리하여 UI를 업데이트하거나 진행 상황을 로깅할 수 있습니다. 이는 특히 긴 코드 생성의 경우 더 나은 사용자 경험을 제공합니다.

스트리밍은 기본 모델이나 그 기능을 변경하지 않습니다. 이는 순수한 전송 메커니즘입니다. 모델은 여전히 전체 프롬프트를 처리하고 전체 응답을 생성합니다. 차이점은 출력이 클라이언트에 전달되는 방식에 있습니다.

Copyfrom openai import OpenAI

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

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

도구 호출 구성 문제

도구 호출(또는 함수 호출)은 LLM이 코드 스니펫 실행이나 데이터베이스 쿼리와 같은 특정 작업을 요청할 수 있게 합니다. 당사 API는 도구 호출을 지원하므로 요청에 함수를 정의하고 모델로부터 구조화된 JSON 응답을 받을 수 있습니다. 이는 외부 시스템과 상호작용해야 하는 고급 코딩 에이전트에 필수적입니다.

도구 호출을 구성하려면 tools 매개변수에 함수 정의 목록을 제공해야 합니다. 각 도구에는 이름, 설명 및 매개변수 스키마가 있어야 합니다. 모델은 프롬프트를 기반으로 도구를 호출할 시기를 결정합니다. 모델이 도구를 호출하기로 결정하면 응답에는 함수 이름과 인수가 포함된 tool_calls 배열이 포함됩니다.

잘못된 JSON 스키마 정의에서 일반적인 문제가 발생합니다. 매개변수 유형과 필수 필드가 정확하게 지정되었는지 확인하세요. 스키마가 유효하지 않으면 모델이 도구를 올바르게 호출하지 못할 수 있습니다. 모델이 예상 동작을 이해하는지 확인하기 위해 간단한 프롬프트로 도구 정의를 테스트하세요.

컨텍스트 창 한도

컨텍스트 창은 프롬프트(입력)와 결과(출력) 모두를 포함하여 모델이 단일 요청에서 처리할 수 있는 텍스트의 최대 양을 정의합니다. 당사 모델은 100,000 토큰의 컨텍스트 창을 제공합니다. 이는 상당한 양의 텍스트이지만 무한하지는 않습니다. 프롬프트와 예상 출력의 합계가 이 한도를 초과하면 API는 오류를 반환합니다.

컨텍스트를 효율적으로 관리하려면 프롬프트의 토큰 사용량을 모니터링하세요. 긴 파일이나 광범위한 대화 기록은 사용 가능한 토큰을 빠르게 소모할 수 있습니다. 한도에 가까워지면 이전 메시지를 자르거나 이전 상호작용을 요약하는 것을 고려하세요. 일부 클라이언트는 창을 슬라이딩하여 이를 자동으로 처리하지만, 예기치 않은 오류를 피하기 위해 한도에 대해 인지하는 것이 가장 좋습니다.

컨텍스트 창에는 시스템 메시지, 사용자 메시지 및 어시스턴트 메시지를 포함하여 모델에 전송된 모든 토큰이 포함됩니다. 긴 코딩 세션 중 원활한 작동을 보장하기 위해 토큰 예산을 적절히 계획하십시오.

키 재생성

API 키를 재생성하는 것은 보안을 보장하는 간단한 프로세스입니다. 키가 노출되었거나 자격 증명을 주기적으로 교체하려는 경우 대시보드에서 새 키를 생성할 수 있습니다. 이전 키는 즉시 무효화되므로 이전 키를 사용하는 진행 중인 요청은 실패합니다.

키를 재생성할 때 모든 클라이언트와 구성 파일을 새 값으로 업데이트해야 합니다. 여기에는 환경 변수, 구성 파일 및 코드 내의 하드코딩된 값이 모두 포함됩니다. 모든 위치를 업데이트하지 않으면 애플리케이션의 일부에서 인증 오류가 발생할 수 있습니다.

당사의 서비스는 키 재생성에 제한이 없습니다. 키를 자주 교체해도 패널티가 없습니다. 이는 특히 공유 환경이나 팀원에게 키를 배포할 때 보안을 유지하기 위한 좋은 관행입니다.

Copycurl https://api.claudecodeapikey.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'