인증과 URL

사용할 API 형식에 맞게 기본 URL과 인증 헤더를 설정하세요.

AI 게이트웨이 API 키를 사용하며 SDK와 직접 HTTP 호출의 URL 구성은 다릅니다.

API 형식별 인증

각 API 형식은 Letsur AI 게이트웨이 API 키를 사용합니다. 월별 사용량과 잔액을 조회하는 플랫폼 API의 관리 API 키와 혼용하지 마세요. SDK를 초기화할 때의 base URL과 직접 HTTP 요청을 보낼 때의 완전한 URL을 구분합니다.

경로	base URL	인증
OpenAI 호환	`https://gw.letsur.ai/v1`	`Authorization: Bearer <API_KEY>`
Messages	`https://gw.letsur.ai`	`x-api-key: <API_KEY>` 권장, `Authorization`도 가능
영상 생성, 작업 조회, 참조 업로드, 파일 링크 발급의 직접 HTTP 요청	`https://gw.letsur.ai` + 각 `/v1/...` 경로	`Authorization: Bearer <API_KEY>`

base URL은 경로마다 다릅니다. OpenAI 호환은 /v1까지 포함하지만, Anthropic 네이티브는 /v1 없이 루트(https://gw.letsur.ai)만 씁니다. Anthropic SDK가 /v1/messages를 내부에서 붙이므로, base URL에 /v1을 또 넣으면 /v1/v1/messages가 되어 호출이 실패합니다.

OpenAI 호환 API 인증

Authorization 헤더에 AI 게이트웨이 API 키를 Bearer <API_KEY> 형태로 담아 보냅니다.

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

cURL 요청


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/chat/completions \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "messages": [{"role": "user", "content": "안녕하세요"}]
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

Python SDK


import os
 
from openai import OpenAI
 
api_key = os.environ.get("LETSUR_API_KEY")
if not api_key:
    raise RuntimeError("LETSUR_API_KEY가 필요합니다.")
 
client = OpenAI(api_key=api_key, base_url="https://gw.letsur.ai/v1")

TypeScript SDK


import OpenAI from 'openai'
 
const apiKey = process.env.LETSUR_API_KEY
if (!apiKey) throw new Error('LETSUR_API_KEY가 필요합니다.')
 
const client = new OpenAI({ apiKey, baseURL: 'https://gw.letsur.ai/v1' })

Anthropic Messages 인증

/v1/messages 경로는 Anthropic 표준 헤더를 씁니다. Letsur AI 게이트웨이 API 키를 쓸 때는 x-api-key를 권장하며, anthropic-version에 API 버전을 담아 보냅니다.

아래 cURL 예제는 요청을 보내고 SDK 예제는 인증된 클라이언트를 초기화합니다. 모두 같은 LETSUR_API_KEY 환경 변수를 사용합니다.

cURL 요청


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/messages \
    --header @- \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "안녕하세요"}]
    }' <<EOF
x-api-key: ${LETSUR_API_KEY}
EOF
)

Python SDK


import os
 
from anthropic import Anthropic
 
api_key = os.environ.get("LETSUR_API_KEY")
if not api_key:
    raise RuntimeError("LETSUR_API_KEY가 필요합니다.")
 
client = Anthropic(api_key=api_key, base_url="https://gw.letsur.ai")

TypeScript SDK


import Anthropic from '@anthropic-ai/sdk'
 
const apiKey = process.env.LETSUR_API_KEY
if (!apiKey) throw new Error('LETSUR_API_KEY가 필요합니다.')
 
const client = new Anthropic({ apiKey, baseURL: 'https://gw.letsur.ai' })

SDK를 쓰면 x-api-key와 anthropic-version 헤더가 자동으로 붙습니다. curl로 직접 호출할 때만 두 헤더를 명시합니다.

직접 HTTP 요청의 URL 구성

Seedance 영상 생성과 후속 작업 API는 개별 레퍼런스의 HTTP 계약을 사용합니다. 예를 들어 루트 https://gw.letsur.ai에 /v1/video/generations를 붙인 완전한 요청 URL은 https://gw.letsur.ai/v1/video/generations입니다. /v1을 두 번 붙이지 않습니다.

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

키 보관

AI 게이트웨이 API 키는 환경변수나 비밀 관리 도구에 보관합니다. 키가 없다면 AI 게이트웨이 > API 키에서 자신의 키를 만듭니다. 키 보관과 만료일은 API 키, 키별 월 한도는 한도에서 확인합니다.

키를 코드나 깃 저장소 또는 클라이언트(브라우저, 모바일 앱)에 그대로 넣지 않습니다. 키가 노출되면 누구나 호출할 수 있으므로 노출된 API 키 대응에 따라 해당 키를 즉시 삭제하고 새 키로 사용처를 복구합니다. 다른 사용자의 키라면 스페이스 Admin에게 즉시 알립니다.

인증 실패

인증에 실패하면 401 응답의 type, detail, error_ref를 확인합니다. 재시도와 문의 기준은 오류 코드를 따릅니다.

`type`	먼저 확인할 것
`missing_credentials`	선택한 API 형식에 맞는 인증 헤더를 요청에 포함했는지 확인합니다
`invalid_credentials`	헤더 형식과 AI 게이트웨이 API 키 값이 정확한지 확인합니다
`api_key_expired`	키의 만료일과 현재 사용할 수 있는 키를 확인합니다

호출이 실패했다면

401에서는 요청한 API 형식의 헤더와 키 상태를 먼저 확인합니다. HTTP 오류의 type, status, error_ref와 작업과 파일 API의 다른 오류 구조, 재시도 기준은 오류 처리에서 확인하세요. 비동기 작업에서는 HTTP 조회 성공과 작업 성공이 별개이므로 Jobs의 작업 상태를 확인합니다.