본문으로 건너뛰기

용어집

플랫폼과 API를 이해하는 데 필요한 용어

계정과 스페이스, API 키, 호출 방식과 작업 ID, 유닛과 비용처럼 렛서 플랫폼 문서에서 사용하는 용어의 뜻을 설명합니다.

페이지 목차

계정, 스페이스 및 역할

플랫폼
렛서 플랫폼은 개인 계정으로 스페이스에 참여하고, 서비스를 이용하거나 구성원과 결제를 관리하는 곳입니다. 초대받았다면 가입과 참여에서 시작합니다.
서비스
렛서 플랫폼의 계정과 스페이스에서 이용하는 제품으로, AI 게이트웨이와 도구 거버넌스가 있습니다. 서비스마다 제공하는 자원, 결과와 제공 범위가 다릅니다. 도구 거버넌스는 Preview 상태로 제공됩니다. 렛서 플랫폼 개요
계정
개인이 렛서 플랫폼에 로그인해 서비스를 이용할 때 사용하는 개인 계정입니다. 계정에는 이름, 가입 이메일과 로그인 방식이 연결됩니다. 하나의 계정으로 여러 스페이스에 참여할 수 있으며, 역할은 스페이스마다 다를 수 있습니다. 내 계정
스페이스
구성원과 역할, 계약 및 결제 정보를 구분하는 범위입니다. 다른 스페이스로 전환하면 화면에 그 스페이스의 구성원, 역할과 결제 정보가 표시됩니다. 스페이스를 전환할 때 확인할 정보
스페이스 구성원
현재 스페이스에 참여한 사람으로, Admin과 Member 역할을 모두 포함합니다. 한 사람의 역할은 스페이스마다 다를 수 있습니다.
스페이스 관리자(Admin)
현재 스페이스의 관리자 역할이며, 화면에는 Admin으로 표시됩니다. 구성원 초대, 역할 변경과 구성원 제거의 범위는 스페이스 구성원에서, AI 게이트웨이 API 키 권한은 구성원 권한에서 각각 확인합니다.
멤버(Member)
현재 스페이스에 참여한 구성원 중 스페이스 관리자가 아닌 사람의 역할이며, 화면에는 Member로 표시됩니다. 키와 유닛을 다룰 수 있는 범위는 구성원 권한에서 확인합니다.

AI 게이트웨이, 모델 및 키

AI 게이트웨이
현재 스페이스에 제공된 여러 공급사의 모델을 하나의 AI 게이트웨이 API 키로 호출하고, 그 사용을 스페이스 단위로 관리하는 서비스입니다. AI 게이트웨이 개요
에셋
AI 게이트웨이에서 사용할 수 있도록 제공되는 자원이며, 모델은 에셋의 한 종류입니다. 현재 상태는 에셋 화면에서 확인합니다.
모델 코드
요청의 model 필드에 지정하는 식별자이며, 에셋 화면에서는 에셋 코드로 표시됩니다. openai/ 같은 공급사 접두사를 추가하지 않고 에셋에 표시된 코드를 그대로 사용합니다.
AI 게이트웨이 API 키
모델 호출에 사용하는 인증 수단입니다. 요청에는 비밀 문자열인 키 값을 포함합니다. 월별 사용량 조회용 관리 API 키와 다릅니다. API 키
개인 키
사람에게 연결된 AI 게이트웨이 API 키로, 콘솔의 API 키 화면에서 만드는 키입니다. 이 키로는 같은 스페이스에서 키를 만든 사람을 기준으로 파일과 작업에 접근합니다. 개인 키와 공유 키의 구분은 키 값을 함께 사용하는 인원수와 관계없습니다. 콘솔과 API 키의 접근 범위
공유 키
개인 소유자에게 연결되지 않은 AI 게이트웨이 API 키입니다. 이 키로는 같은 스페이스에서 키 자체를 기준으로 파일과 작업에 접근합니다. 새로 만든 키는 기존 키의 접근 권한을 이어받지 않습니다. 콘솔과 API 키의 접근 범위
관리 API 키 (Management Key)
mk_...로 시작하는 키입니다. 키가 발급된 스페이스의 AI 게이트웨이 월별 사용량과 현재 잔액을 관리 API로 조회할 때 씁니다. 모델 호출에는 사용하지 않습니다.

호출과 결과

base URL
API 요청을 보내는 기본 주소이며, 호출 대상과 API 형식에 따라 주소가 다릅니다. AI 게이트웨이의 OpenAI 호환 및 Anthropic 네이티브 주소와 사용량과 잔액 조회용 관리 API 주소가 각각 있습니다.
엔드포인트 (endpoint)
HTTP 메서드와 경로의 조합입니다(예: POST /v1/chat/completions). 모델마다 지원하는 엔드포인트가 다릅니다. base URL과 경로를 조합할 때는 SDK 경로가 중복되지 않게 합니다. 직접 HTTP 요청의 URL 구성
동기 호출
결과를 응답으로 바로 받는 호출입니다. 작업 ID를 반환하는 이미지 모델에 Prefer: respond-async 헤더 없이 보낸 요청도 동기 호출이며, 이때는 응답에 작업 ID가 함께 들어 있습니다. 동기 호출과 비동기 호출
비동기 호출
게이트웨이가 요청을 작업으로 접수하면, 응답으로 받은 작업 ID로 결과를 조회하는 호출입니다. 영상 생성 요청과, 작업 ID를 반환하는 이미지 모델에 Prefer: respond-async 헤더를 보낸 요청이 해당합니다. 동기 호출과 비동기 호출
Image Generations
프롬프트로 이미지를 만드는 엔드포인트입니다. 모델에 따라 OpenAI Images API와 같은 형식으로 이미지를 응답 본문에 담아 돌려주거나, 이미지 URL과 작업 ID를 돌려줍니다. 지원 모델
Image Edits
입력 이미지와 프롬프트를 multipart 요청으로 보내 이미지를 편집하는 엔드포인트입니다. 파일 조건과 결과 형식
스트리밍
생성 중인 응답을 조각으로 받는 방식이며, 스트리밍을 지원하는 모델에 "stream": true를 지정해 요청합니다. 이벤트와 종료 신호는 API 형식마다 다릅니다. 기능별 명세 위치
작업 ID (job ID)
비동기 호출이 작업으로 접수됐을 때 접수 응답의 id로 받는 식별자이며, 같은 작업을 조회할 때 사용합니다. 작업 ID를 반환하는 이미지 모델에서는 동기 응답의 id로도 같은 작업을 조회할 수 있습니다. 결과 파일의 미디어 ID와 구분합니다. Jobs
미디어 ID (media_id)
생성 결과 파일의 식별자입니다. 링크가 만료돼도 파일이 보관 중이면 같은 ID로 다운로드 링크를 다시 발급받을 수 있습니다. Media Links
참조 파일 (reference)
영상 생성의 입력으로 사용하는 이미지, 영상 또는 오디오입니다. 로컬 파일은 References로 업로드한 뒤, 응답으로 받은 reference 값을 생성 요청에 지정합니다.
API 오류 응답
공통 모델 호출 오류는 type, title, status, detail, error_ref 구조를 사용합니다. 작업 조회와 파일 링크 발급의 오류에는 error.code 형식도 사용됩니다. 오류 처리
error_ref
공통 모델 호출 오류의 추적용 식별자입니다. 문의할 때 함께 전달하면 렛서가 문제를 추적할 수 있습니다. 오류 응답 구조

사용량과 비용

유닛 (unit)
AI 게이트웨이 사용량과 잔액의 단위입니다. 이미 사용한 양과 현재 보유한 양은 서로 다른 값입니다. 유닛은 VAT 포함 KRW 미결제 금액과도 다릅니다. 유닛
초과 사용량
보유 유닛으로 차감하지 못하고 기록된 사용량(unit)입니다. 렛서는 초과 사용량을 월간 정산 때 원화로 환산해 청구합니다. 잔액이 소진됐을 때
호출 차단 상태
보유 유닛이 없고 초과 사용도 허용되지 않아 API 호출이 중단된 상태입니다. 유닛 화면에서 확인하는 값
미결제 금액
결제 화면에 표시되는 VAT 포함 KRW 금액입니다. 청구서가 발행되면 늘어나고, 납부 완료가 반영되면 납부한 금액만큼 줄어듭니다. 거래 내역에 유닛 구매가 표시되어도 미결제 금액의 납부가 완료된 것은 아닙니다. 청구와 납부가 미결제 금액에 반영되는 방식
정산 (settlement)
Batch의 비용이 확정되는 과정이며, 처리 상태와 별도로 settlement_status로 확인합니다. settlement_status가 settled이고 settled_units가 null이 아니면 settled_units의 유닛 금액이 확정 비용입니다. 정산 중의 null은 0이 아닙니다. Batch의 확정 비용 확인하기
API 키 월 한도
API 키 한 개의 월 사용 상한이며, 한 구성원의 여러 개인 키를 합산하는 구성원 월 한도와 별도로 적용됩니다. 한도 종류 선택
구성원 월 한도
현재 스페이스에서 한 구성원이 만든 개인 API 키의 사용량을 합산한 월 상한이며, API 키 월 한도와 함께 적용됩니다. 구성원 월 한도 관리하기
estimated_cost
호출 한 건의 비용 객체로, 지원되는 동기 호출의 응답에 포함됩니다. 실제 청구액과 다를 수 있습니다. 동기 응답에서 비용 확인하기