첫 API 호출
모델과 키를 준비해 첫 응답 받기
Chat Completions를 지원하는 모델을 선택하고 cURL 또는 Python으로 요청을 보내 응답 본문과 종료 이유, 사용량을 확인합니다.
페이지 목차
시작 전 준비
텍스트 모델에 요청 한 건을 보내고 응답 본문, 종료 이유와 사용량을 확인하면 첫 호출이 끝납니다. 요청을 보내기 전에 다음을 준비하세요.
- AI 게이트웨이 API 키
현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.
- 모델 코드와 지원 엔드포인트
에셋에서 Chat Completions를 지원하는 모델을 선택하고 정확한 코드를 확인합니다.
- 실행 환경
패키지를 설치할 수 있는 Python 3 환경(가상 환경 권장) 또는 cURL을 준비합니다. Python 예제는 실행할 때 API 키와 모델 코드를 입력받습니다.
- 스페이스의 유닛과 월 한도
키를 사용할 스페이스가 맞는지 확인하세요. 유효한 키가 있어도 보유 유닛과 호출 차단 상태, 키와 구성원의 월 한도가 요청을 제한할 수 있습니다.
API 형식 선택
아래 예제는 OpenAI 호환 Chat Completions 형식의 비스트리밍 호출로, 텍스트 응답 전체를 한 번에 받습니다. 사용하는 SDK에 따라 base URL이 다릅니다.
| 사용할 방식 | base URL과 다음 단계 |
|---|---|
| OpenAI 호환 SDK 또는 HTTP | https://gw.letsur.ai/v1. 아래 Chat Completions 첫 요청으로 진행 |
| Anthropic SDK 또는 Claude Code | https://gw.letsur.ai. Messages로 진행 |
기존 OpenAI 호환 코드에서는 base URL, API 키와 모델 코드를 바꾸고, 요청 필드와 기능을 에셋에서 확인한 모델의 지원 범위에 맞춥니다. Chat Completions, Responses, Messages 가운데 사용할 형식과, 각 형식에서 스트리밍, 이미지 입력, 도구 호출을 지정하는 위치는 텍스트 생성하기에서 비교합니다.
첫 API 요청 보내기
모델 코드 확인하기
AI 게이트웨이 > 에셋에서 Chat Completions를 지원하는 모델 코드를 선택합니다. 표시된 코드를 그대로 사용하며, 공급사 접두사를 임의로 추가하거나 코드 일부를 제거하지 않습니다.
키와 모델 코드 준비하기
사용할 키가 없다면 AI 게이트웨이 > API 키에서 자신의 키를 만들고 안전한 시크릿 저장소에 보관합니다. Python 예제는 실행할 때 키와 모델 코드를 입력받으므로 별도의 셸 설정 없이 시작할 수 있습니다. cURL을 사용한다면 실행 환경의 시크릿 설정으로
LETSUR_API_KEY를 준비하고, 요청 본문의<MODEL_CODE>를 확인한 코드로 바꾸세요.키 값을 코드, 셸 히스토리, 브라우저나 모바일 앱에 직접 저장하지 마세요공용 실행 환경에서는 키가 명령어 인수에 노출되지 않는 Python 예제를 사용하세요.
요청 보내기
사용할 방법 하나를 선택해 실행하세요. cURL과 Python SDK 예제는 같은 모델에 같은 요청을 보냅니다.
응답을 받지 못해도 같은 요청을 바로 다시 보내지 마세요timeout이나 응답 유실이 발생해도 원래 요청은 처리됐을 수 있습니다. 다시 보내면 별도 호출과 추가 비용이 발생할 수 있으므로, 먼저 동기 호출의 재시도 기준을 확인하세요. SDK 예제는 자동으로 재시도하지 않습니다.
cURL
LETSUR_API_KEY가 설정된 환경에서 실행합니다.<MODEL_CODE>를 사용할 모델 코드로 바꾸세요.cURLcurl https://gw.letsur.ai/v1/chat/completions \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{"model":"<MODEL_CODE>","messages":[{"role":"user","content":"안녕하세요"}]}'
성공 응답 확인
모델이 생성한 응답 본문과 usage 객체가 출력되면 모델을 호출해 응답을 받았다는 뜻입니다. 답변이 완성됐는지는 아래 종료 이유와 답변 내용을 함께 보고 판단합니다.
Python: 응답 본문, 응답 종료 이유, 토큰 사용량이 포함된 usage 객체가 차례로 출력됩니다.
cURL: JSON의 choices[0].message.content에서 응답 본문을, choices[0].finish_reason에서 종료 이유를 확인하세요. 아래는 Chat Completions 응답의 일부를 보여주는 예시이며, 본문과 사용량, 비용 값은 실제 호출 결과가 아닙니다.
{
"choices": [
{
"message": { "role": "assistant", "content": "..." },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 48,
"total_tokens": 60
},
"estimated_cost": {
"amount": "0.00032400",
"currency": "unit"
}
}종료 이유(finish_reason)가 stop이면 모델이 응답 생성을 마쳤다는 뜻입니다. 실제 답변 내용이 기대와 맞는지도 확인하세요. 답변이 잘리거나 비어 있다면 종료 이유별 다음 행동을 먼저 확인합니다. 다시 요청하면 별도 호출과 추가 비용이 발생할 수 있으므로 같은 요청을 자동 반복하지 마세요.
usage.prompt_tokens는 입력 토큰 사용량,usage.completion_tokens는 출력 토큰 사용량입니다.- 최상위
estimated_cost는 이 비스트리밍 호출의 비용 객체입니다.usage내부 필드가 아닙니다. 호출별 비용을 추적하는 데 사용하는 값이며 최종 납부 금액과는 다릅니다. 호출 한 건의 비용을 고객 작업과 연결해 저장하는 방법은 요청별 비용에서 확인합니다.
문제 해결
| 증상 | 다음 행동 |
|---|---|
401 | 키 값과 Authorization: Bearer 헤더를 확인합니다 |
402 insufficient_units | 유닛에서 보유 유닛과 호출 차단 상태를 확인합니다 |
403 ip_not_allowed | 현재 요청의 출발지 IP가 키의 IP 허용 목록에 포함됐는지 확인합니다 |
404 model_not_found | 에셋에서 현재 모델 코드를 다시 확인합니다 |
429 policy_limit_exceeded, 429 usage_limit_exceeded | 한도에 도달했을 때에서 오류 코드별 확인 순서를 따릅니다 |
429 rate_limit_exceeded | 응답의 안내에 따라 간격을 두고 재시도합니다 |
502, 503, 504 | error_ref를 보관하고 동기 호출의 재시도 기준을 확인합니다. 응답을 받지 못해도 모델이 요청을 처리했을 수 있으므로 같은 요청을 즉시 반복하지 않습니다 |
표에 없는 오류이거나 같은 오류가 계속되면 오류 type별 대응을 확인합니다. 해결되지 않으면 지원에 전달할 정보를 준비해 문의합니다.
첫 호출 이후
첫 응답을 받았다면 하려는 일에 맞춰 다음 안내로 이동하세요.
- 텍스트 모델로 애플리케이션 구현: 텍스트 생성하기에서 API 형식을 선택하고, 선택한 형식의 명세에서 요청 필드, 스트리밍, 응답과 오류를 확인합니다.
- 이미지나 영상 만들기: 이미지와 영상 만들기에서 사용할 모델의 호출 경로와 결과를 받는 방법을 확인합니다.
- 많은 요청을 일괄 처리: 여러 요청을 Batch로 처리하기에서 요청을 파일로 묶어 제출하는 방법을 확인합니다.
- 기존 도구에 연결: 외부 도구별 설정을 선택합니다.