Models
현재 스페이스에서 사용할 모델 코드와 단가 조회
AI 게이트웨이 API 키가 연결된 스페이스의 모델 코드, 단가와 Batch 지원 여부를 조회하며 모델 목록과 실시간 호출 상태를 구분합니다.
페이지 목차
https://gw.letsur.ai/v1/modelsAuthorization: Bearer <API_KEY>필요한 조회 선택하기
GET /v1/models는 요청에 사용한 AI 게이트웨이 API 키가 연결된 스페이스에서 조회할 수 있는 모델의 코드, 단가와 Batch 지원 여부를 반환합니다. 모델 목록은 실시간 호출 성공 여부를 나타내지 않습니다.
| 하려는 일 | 확인할 곳 |
|---|---|
| 모델 선택 목록 만들기와 모델 코드 확인 | 이 API 응답의 data[].id에서 모델 코드를 읽음. 단가와 Batch 지원 여부도 함께 확인 |
| 호출 오류나 지연 확인 | 업스트림 응답 상태 조회. 정상 항목이 빠지므로 모델 선택 목록용으로 쓰지 않음 |
| 호출할 API와 입력 한도 확인 | 에셋에서 모델을 선택하는 방법 |
호출 환경 준비하기
- 조회할 스페이스의 AI 게이트웨이 API 키
콘솔에서 선택한 스페이스는 API 요청에 전달되지 않습니다. 키가 연결된 스페이스를 먼저 확인하세요. 관리 API 키는 사용하지 않습니다. 인증 헤더, SDK 기본 URL과 키 보관 방법은 인증과 기본 URL에 있습니다.
- 키를 보관한 서버에서 조회조건부
웹 앱에서 목록을 쓸 때 필요합니다. 키를 보관한 서버에서 목록을 조회하고, 키는 브라우저 코드에 넣지 마세요.
아래 예제는 서버나 로컬 셸의 LETSUR_API_KEY 환경 변수를 읽습니다. Python 서버에서는 OpenAI SDK의 models.list()로 같은 목록을 조회할 수 있습니다.
요청 파라미터
본문과 페이지네이션 파라미터는 없습니다. 현재 스페이스에서 조회할 수 있는 모델 목록이 한 번의 응답으로 반환됩니다.
모델 목록 조회 예시
아래 예제는 현재 스페이스에서 조회할 수 있는 모델 목록을 한 번의 요청으로 가져옵니다. 응답은 object와 data로 구성됩니다.
cURL
curl "https://gw.letsur.ai/v1/models" \
-H "Authorization: Bearer $LETSUR_API_KEY"응답 (200)
요청이 성공하면 200과 함께 모델 배열이 반환됩니다. 응답에는 pagination 필드가 없습니다.
| 필드 | 설명 |
|---|---|
data | 현재 스페이스에서 조회할 수 있는 모델 객체의 배열입니다 |
data[].id | 모델 코드입니다. 호출할 때 model 필드에 이 값을 지정합니다 |
data[].object | 항상 "model"입니다 |
data[].created | 모델이 추가되거나 갱신된 시각(Unix epoch)입니다 |
data[].owned_by | OpenAI 호환 응답에서 letsur로 반환됩니다. 이 값은 실제 모델 공급사를 나타내지 않습니다 |
data[].supports_batch | 모델의 Batch 지원 여부입니다. 지원 API와 스페이스의 신규 제출 조건은 별도로 확인합니다 |
data[].max_input_tokens | 현재 값은 null입니다. 무제한을 뜻하지 않습니다. 모델의 토큰 한도는 에셋 화면에서 확인하며, 입력 한도와 출력 상한은 구분합니다 |
data[].pricing | 모델 단가 객체입니다. 단가 정보가 없으면 null일 수 있습니다 |
data[].pricing.currency | 단가의 표시 단위입니다. 값은 unit입니다 |
data[].pricing.usage[] | 과금 항목별 단가 목록입니다. 적용 조건은 아래 단가 항목 읽기의 필드로 구분합니다 |
아래는 일부 필드를 보여 주는 설명용 예시입니다. 실제 모델의 Batch 지원 여부는 현재 응답에서 확인합니다.
{
"object": "list",
"data": [
{
"id": "<MODEL_CODE_A>",
"object": "model",
"created": 1730000000,
"owned_by": "letsur",
"supports_batch": true
},
{
"id": "<MODEL_CODE_B>",
"object": "model",
"created": 1729000000,
"owned_by": "letsur",
"supports_batch": false
}
]
}단가 항목 읽기
pricing.usage[]의 각 항목은 다음 필드를 포함합니다. 단가는 실제 요청 한 건의 비용과 다릅니다. 응답에 기록된 비용을 대조할 때 현재 단가만으로 과거 호출의 비용을 다시 계산하지 않습니다.
| 필드 | 설명 |
|---|---|
component | 입력, 출력 같은 과금 항목입니다. 값의 예는 input, output입니다 |
unit | 단가를 적용할 사용량 단위입니다. 값의 예는 token_input, token_output과 영상 모델의 minute입니다 |
amount | 사용량 단위당 unit 단가(숫자)입니다 |
currency | 값은 unit입니다 |
when | 단가 적용 조건입니다. 해상도 같은 생성 조건이 그 예입니다. 조건이 없는 항목은 null입니다 |
component와 unit 값이 같아도 when이 다르면 단가가 적용되는 조건도 다릅니다. 고객 시스템에 비용을 기록할 때는 호출이나 작업별 비용을 사용합니다.
제약과 공통 오류
- 유효한 API 키로 현재 스페이스의 모델을 조회합니다. 보유 유닛이 없거나 API 키의 월 한도에 도달했더라도 모델 목록은 조회할 수 있습니다.
- 이 엔드포인트 고유의 오류는 없습니다. 인증 오류를 받았다면 오류 type별 대응에서 확인할 항목을 찾습니다.
업스트림 응답 상태 조회
장애, 지연과 상태 확인 불가 항목, 상태 값과 유효기간, 조회 오류 처리는 업스트림 응답 상태 API에서 확인하세요.