본문으로 건너뛰기

인증과 기본 URL

API 형식에 맞는 주소와 인증 헤더 구성

AI 게이트웨이 API 키를 사용하는 OpenAI 호환 및 Anthropic Messages 인증을 비교하고, SDK의 기본 URL과 직접 HTTP 요청 주소를 구분합니다.

페이지 목차

API 형식별 인증

모델을 호출하거나 영상과 Batch의 후속 작업을 요청할 때는 Letsur AI 게이트웨이 API 키를 사용합니다. API 형식별로 기본 URL과 인증 헤더가 다릅니다. 월별 사용량과 잔액 조회에 사용하는 관리 API 키는 이 키와 다르므로 혼용하지 마세요.

키가 없다면 AI 게이트웨이 > API 키에서 자신의 키를 만듭니다. 키를 만들고 보관하는 방법과 만료일을 설정하는 방법은 API 키 만들기와 관리에서 확인합니다.

사용할 모델의 정확한 코드와 지원 API를 모델 선택에서 먼저 확인하세요. 이미지나 영상 같은 결과 종류만으로 호출 경로를 결정하지 않습니다.

다음 표는 SDK 초기화에 지정하는 기본 URL과 직접 HTTP 요청에 사용하는 완전한 URL을 나누어 보여 줍니다.

API 형식기본 URL 또는 요청 URL인증 헤더
OpenAI 호환SDK 기본 URL https://gw.letsur.ai/v1Authorization: Bearer <API_KEY>
Anthropic MessagesSDK 기본 URL https://gw.letsur.aix-api-key: <API_KEY> 권장(Authorization도 가능), anthropic-version 함께 전송
영상 생성, 작업 조회, 참조 업로드, 파일 링크 발급의 직접 HTTP 요청https://gw.letsur.ai + 각 /v1/... 경로Authorization: Bearer <API_KEY>
Anthropic SDK의 기본 URL에 /v1을 붙이면 호출이 실패합니다

SDK의 기본 URL은 API 형식마다 다릅니다. OpenAI 호환 형식의 기본 URL은 /v1까지 포함하지만, Anthropic Messages 형식은 /v1 없이 루트(https://gw.letsur.ai)만 사용합니다. Anthropic SDK가 /v1/messages를 내부에서 추가하므로, 기본 URL에 /v1을 다시 지정하면 요청 경로가 /v1/v1/messages가 되어 호출이 실패합니다.

OpenAI 호환 API 인증

Authorization 헤더에 AI 게이트웨이 API 키를 Bearer <API_KEY> 형식으로 지정합니다.

아래 cURL 예제는 요청을 보내고 Python SDK 예제는 인증된 클라이언트를 초기화합니다. 두 예제 모두 서버 측 환경 변수 LETSUR_API_KEY를 읽고, 코드나 명령어에 키 값을 직접 포함하지 않습니다.

SDK 예제는 자동 재시도를 끕니다. timeout이나 응답 유실 뒤에 다시 보낸 요청은 별도 호출로 처리되어 비용이 추가될 수 있습니다. 다음 요청을 보낼지는 동기 호출의 재시도 기준에 따라 판단하세요.

cURL
curl https://gw.letsur.ai/v1/chat/completions \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_CODE>", "messages": [{"role": "user", "content": "안녕하세요"}] }'

Anthropic Messages 인증

/v1/messages로 요청을 보낼 때는 Anthropic 표준 헤더를 사용합니다. Letsur AI 게이트웨이 API 키는 x-api-key 헤더로 보내기를 권장합니다. anthropic-version 헤더에는 API 버전을 지정합니다. SDK를 사용하면 x-api-key와 anthropic-version 헤더가 자동으로 추가되므로, curl로 직접 호출할 때만 두 헤더를 명시합니다.

아래 cURL 예제는 요청을 보내고 Python SDK 예제는 인증된 클라이언트를 초기화합니다. 두 예제 모두 서버 측 환경 변수 LETSUR_API_KEY를 사용하고, 코드나 명령어에 키 값을 직접 포함하지 않습니다. OpenAI 호환 예제와 마찬가지로 SDK 예제는 자동 재시도를 끕니다. timeout이나 응답 유실 뒤에는 같은 재시도 기준으로 다음 요청 여부를 판단합니다.

cURL
curl https://gw.letsur.ai/v1/messages \ -H "x-api-key: $LETSUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_CODE>", "max_tokens": 1024, "messages": [{"role": "user", "content": "안녕하세요"}] }'

직접 HTTP 요청의 URL 구성

영상 생성과 후속 작업을 요청할 때는 각 API 레퍼런스에 명시된 HTTP 메서드와 경로, 요청 형식을 따릅니다. 예를 들어 루트 https://gw.letsur.ai와 /v1/video/generations를 연결한 완전한 요청 URL은 https://gw.letsur.ai/v1/video/generations입니다. /v1을 중복해 지정하지 않습니다.

같은 Bearer 인증을 사용한다는 사실만으로 OpenAI SDK 메서드를 그대로 사용할 수 있다고 가정하지 않습니다. 실행 예제는 생성 요청하고 결과 파일 받기에서 확인합니다.

키 보관

노출된 키로는 누구나 모델을 호출할 수 있습니다

키 값을 코드, 깃 저장소 또는 클라이언트(브라우저, 모바일 앱)에 직접 포함하지 마세요. 보관 방법은 키 보관과 삭제 전 점검에서, 노출되었을 때의 대응은 노출된 API 키 대응에서 확인합니다.

인증 실패

인증 실패(HTTP 401)의 type별 대응과 재시도 및 문의 기준은 오류 처리에서 확인합니다.

인증 후 요청 보내기

처음 호출한다면 모델과 키를 준비해 첫 응답 받기를 따릅니다. 선택한 모델의 입력 필드와 한도는 모델별 지원 API에 연결된 명세와 모델별 가이드에서 함께 확인하세요.

비동기 작업을 구현한다면 생성 요청하고 결과 파일 받기 또는 Batch 처리를 따릅니다. 생성 요청의 접수, 처리 완료, 파일 준비와 비용 확정을 같은 상태로 판단하지 않습니다. 각 명세에서 어떤 작업 ID를 쓰는지, 이후 상태를 어떻게 조회하는지 확인하세요.