본문으로 건너뛰기

FAQ

자주 발생하는 문제의 원인과 해결 방법

로그인, 모델 호출, 영상 작업, API 키, 사용량과 결제에서 겪는 증상별로 먼저 확인할 것과 이동할 안내, 지원 요청 방법을 안내합니다.

페이지 목차

모델 코드를 찾거나 응답이 잘리는 문제는 모델과 호출, 영상 작업이나 Batch 결과 문제는 이미지, 영상 및 Batch, 재시도와 문의 방법은 오류와 지원에서 확인하세요.

가입, 계정 및 스페이스

계정에 로그인할 수 없습니다.

이메일과 Google 중 가입할 때 선택한 로그인 방식을 확인하고 로그인 방식에 맞는 계정 복구 안내를 따르세요. 복구 후에도 로그인할 수 없다면 이메일로 로그인 지원 요청하기를 따릅니다.

참여한 스페이스가 보이지 않습니다.

현재 로그인한 계정과 안내받은 스페이스 이름을 대조하세요. 회사 계정과 개인 계정 중 스페이스에서 사용할 계정으로 로그인해야 합니다. 목록에 계속 없으면 Admin에게 참여 상태 확인을 요청하고 초대 참여 결과 확인을 따릅니다.

Admin과 Member는 무엇이 다른가요?

구성원 초대, 역할 변경과 구성원 제거는 Admin이 할 수 있습니다. 역할은 스페이스마다 따로 적용됩니다. 스페이스에서 역할별로 할 수 있는 작업은 스페이스 구성원, AI 게이트웨이 API 키를 다룰 수 있는 범위는 구성원 권한에서 확인합니다.

모델과 호출

모델 코드와 지원 API는 어디서 확인하나요?

AI 게이트웨이 > 에셋에서 현재 스페이스의 모델 코드와 지원 API를 확인하세요. 프로그램에서 확인하려면 GET /v1/models를 호출합니다. 이 엔드포인트는 현재 스페이스에서 조회할 수 있는 모델 목록을 OpenAI 호환 형식으로 반환합니다. 모델을 비교하고 선택하는 방법은 모델 선택에 있습니다.

OpenAI SDK를 사용할 수 있나요?

지원되는 OpenAI 호환 엔드포인트에서 사용할 수 있습니다. base URL은 https://gw.letsur.ai/v1입니다. 요청에는 AI 게이트웨이 API 키와 에셋의 모델 코드를 사용합니다. 첫 API 호출에서 준비와 성공 확인까지 진행하세요.

Claude Code나 Anthropic SDK도 사용할 수 있나요?

Messages를 지원하는 모델에서 사용할 수 있습니다. Anthropic 네이티브 base URL은 https://gw.letsur.ai입니다. 연결 조건과 설정은 Claude Code 연결을 따르세요.

응답을 스트리밍으로 받고 싶습니다.

모델과 엔드포인트의 스트리밍 지원 여부를 먼저 확인하세요. 스트리밍 이벤트, 종료 신호와 usage가 반환되는 위치는 API 형식마다 다르므로, API 형식별 스트리밍 명세 위치에서 사용할 형식의 절을 찾습니다.

응답은 받았는데 답변이 잘리거나 비어 있습니다.

HTTP 200이나 텍스트 일부를 받았다고 해서 답변이 완성된 것은 아닙니다. 사용한 API의 종료 상태를 확인하세요.

도구 실행을 요청한 응답이라면 사용한 API의 형식에 맞춰 도구를 실행하고 그 결과를 다음 요청에 포함해 보냅니다. 스트리밍이 중단됐다면 종료 신호를 받았는지 확인합니다. 종료 신호를 받지 못했다면 수신한 내용을 부분 응답으로 보관합니다. 비용 필드가 없거나 null이어도 무료로 처리하지 말고 호출별 비용 기록 기준을 따릅니다.

같은 요청을 다시 보내면 추가 비용이 발생할 수 있습니다

다시 보낸 요청은 별도 호출로 처리됩니다. 같은 요청을 자동으로 반복하지 마세요.

이미지, 영상 및 Batch

영상 작업의 진행 상태는 접수 때 받은 작업 ID로 같은 작업을 조회해 확인합니다.

이미지 생성과 편집에 별도 OpenAI API 키가 필요한가요?

필요하지 않습니다. 현재 모든 스페이스에서 기존 AI 게이트웨이 API 키로 Image Generations와 Image Edits를 호출해 gpt-image-2를 사용할 수 있습니다. Chat Completions로 이미지 생성 결과를 반환하는 모델이 에셋에 제공된다면 같은 키로 Chat Completions를 호출해 그 모델을 사용할 수 있습니다. 모델마다 호출하는 엔드포인트는 이미지와 영상 만들기의 모델별 호출 경로에서 확인하세요.

영상 생성 요청을 보냈는데 작업 ID를 받지 못했습니다.

응답을 받지 못했어도 요청은 접수됐을 수 있습니다.

생성 요청을 다시 보내면 작업과 비용이 중복될 수 있습니다

접수 여부를 확인하기 전에는 생성 요청을 다시 보내지 마세요.

스페이스 이름, 요청 시각, 모델 코드와 확보한 오류 코드를 플랫폼 내 문의 기능에 남겨 접수 여부를 확인합니다. 자세한 대응은 작업 ID 저장과 접수 확인을 따릅니다.

영상 생성은 성공했는데 파일을 받지 못했습니다.

작업이 성공해도 파일은 아직 받을 수 없는 상태일 수 있으므로 같은 작업의 파일 상태를 먼저 확인하세요. 다운로드 링크만 만료됐고 파일이 보관 중이면 같은 미디어 ID로 링크를 다시 발급받습니다. 파일 보관이 만료됐다면 새 링크를 발급받아도 파일을 복구할 수 없습니다. 상태별 다음 행동은 결과 파일 받기에 있습니다.

영상 작업 응답에 비용이 없습니다. 무료인가요?

usage 필드가 없어도 무료로 판단하지 않습니다. 작업 상태별 확인 방법은 요청별 비용의 영상 작업 비용 확인에 있습니다.

Batch가 완료됐는데 일부 결과나 비용이 보이지 않습니다.

Batch 처리가 완료됐다고 해서 모든 행이 성공하거나 비용 정산까지 끝난 것은 아닙니다. Batch의 행별 결과, 파일과 확정 비용 확인을 따르세요.

API 키와 인증

AI 게이트웨이 API 키 원문을 잃어버렸습니다. 다시 볼 수 있나요?

다시 볼 수 없습니다. 원문은 생성 완료 화면에서 한 번만 표시됩니다. 키가 노출되지 않았다면 사용처를 새 키로 전환하고, 이전 키가 더 이상 사용되지 않는지 확인한 뒤 이전 키를 삭제합니다. 자세한 순서는 노출되지 않은 키 교체하기를 따릅니다. 노출됐다면 긴급 대응을 먼저 진행하세요.

AI 게이트웨이 API 키가 노출됐습니다.

새 키로 전환할 때까지 노출된 키를 활성 상태로 두지 마세요. 다음 순서로 대응합니다.

  1. 노출된 키를 즉시 비활성화합니다. 비활성화하면 그 키의 새 호출이 바로 중단됩니다.
    • 자신의 키: 내 키에서 그 행의 관리 메뉴로 비활성화합니다.
    • 다른 사용자의 키: Admin은 전체 키에서 비활성화하고, Member는 Admin에게 즉시 비활성화를 요청합니다.
  2. 새 키를 만들고 코드, 자동화와 외부 도구의 키 값을 교체합니다.
  3. 노출된 API 키 대응에 따라 노출 이후의 사용량을 확인한 뒤 노출된 키를 삭제합니다.
API 키가 만료됐습니다. 만료일을 늘리거나 다시 활성화할 수 있나요?

할 수 없습니다. 만료일은 한 번 설정하면 바꾸거나 해제할 수 없고, 만료된 키는 삭제만 할 수 있습니다. 새 키를 만들어 사용처의 키 값을 바꾼 뒤 만료된 키를 삭제하세요. 순서는 만료된 키 대신 새 키 사용하기에 있습니다.

401 인증 오류가 반환됩니다.

먼저 요청 주소로 호출 대상 API를 확인하세요.

  • AI 게이트웨이 요청(https://gw.letsur.ai): AI 게이트웨이 API 키를 사용합니다. 응답의 type 값(invalid_credentials, missing_credentials, api_key_expired)을 확인합니다. invalid_credentials라면 키가 비활성 상태이거나 삭제되지 않았는지도 확인합니다. OpenAI 호환 경로와 Anthropic Messages는 헤더가 다르므로 AI 게이트웨이의 경로별 인증 형식과 오류 원인을 대조합니다.
  • 관리 API 요청(https://openapi.letsur.ai/v1): 관리 API 키(mk_...)를 사용합니다. 관리 API의 요청 주소와 Bearer 인증 헤더를 대조합니다.
AI 게이트웨이 API 키와 관리 API 키는 같은가요?

다릅니다. AI 게이트웨이 API 키는 모델 호출에, 관리 API 키(mk_...)는 스페이스의 월별 사용량과 유닛 잔액 조회에 사용합니다. 관리 API 키가 필요하면 관리 API 키 발급 권한과 인증을 확인하세요.

사용량, 한도 및 결제

API 키의 월 한도를 비워 두면 어떻게 되나요?

그 키에는 월 한도가 설정되지 않지만, 구성원 월 한도와 보유 유닛에 따른 제한은 유지됩니다. 실제 서비스에서 키를 사용하기 전에 한도가 적용되는 시점과 예외를 확인하고 키별 월 한도 설정 여부를 검토하세요.

월 한도를 설정하면 지출이 그 금액을 넘지 않나요?

월 한도만으로 최종 지출이 설정값 이하라고 보장할 수는 없습니다. 한도를 넘을 수 있는 경우는 월 사용 한도에서 확인합니다.

429 policy_limit_exceeded 또는 usage_limit_exceeded가 반환됩니다.

같은 요청을 반복하지 말고 응답의 type과 상세를 확인하세요. policy_limit_exceeded이면 응답이 안내하는 한도와 사용량을 확인합니다. usage_limit_exceeded를 키 월 한도 초과로 단정하지 않습니다. 적용 대상과 해제 조건을 확인하는 순서는 월 사용 한도의 한도에 도달했을 때에 있습니다.

이번 달 사용량은 어디서 보나요?

AI 게이트웨이 > 사용량 분석에서 월간 기준으로 에셋 및 API 키별 누적 unit과 호출 수를 확인합니다. 비교 방법은 사용량 분석을 따르세요.

콘솔에 자주 접속하지 않고 사용량과 잔액을 확인할 수 있나요?

관리 API 키가 연결된 스페이스의 사용량과 잔액을 서버에서 조회할 수 있습니다. 조회할 값과 호출별 비용을 기록하는 방법은 요금 및 사용량 안내에서 확인합니다.

estimated_cost, 분석 사용량과 실제 결제는 같은 값인가요?

다릅니다. 호출 한 건의 비용, 누적 unit과 VAT 포함 KRW 미결제 금액은 대상, 기간과 단위가 다릅니다. 비교할 때 맞춰야 할 조건은 요금 및 사용량 안내에서 확인하세요.

결제 메뉴나 필요한 작업이 보이지 않습니다.

현재 스페이스를 확인하세요. 메뉴가 없거나 작업이 보이지 않으면 Admin에게 역할과 스페이스의 결제 활성화 상태 확인을 요청합니다. 결제 메뉴를 사용할 수 있는 조건을 따르세요.

오류와 지원

어떤 오류를 재시도해야 하나요?

실패한 요청의 종류부터 확인하세요. 요청 종류별로 다시 보내도 되는지와 비용 확인을 문의하는 방법은 요청 단계별 재시도 기준에 있습니다.

응답을 받지 못한 동기 호출도 이미 처리되어 비용이 발생했을 수 있습니다

Batch의 단계별 복구는 Batch 문제 해결을 따르세요.

지원 요청하기

안내대로 조치해도 오류가 계속된다면 플랫폼 내 문의 기능으로 문의하세요. 로그인한 뒤 화면 오른쪽 위의 사용자 메뉴에서 문의를 선택합니다. 문의 목록에서 내 문의를 열면 처리 상태와 답변을 확인할 수 있습니다. 문의가 종료되기 전에는 메시지를 추가할 수 있습니다.

  • 모든 문의: 스페이스 이름, 계정 이메일, 발생 시각과 보이는 증상을 남깁니다.
  • API 오류 문의: 확보한 엔드포인트, HTTP 상태, 응답의 type 또는 error.code, error_ref와 작업 ID도 함께 남깁니다. 응답 헤더에 x-letsur-request-id가 있으면 그 값도 함께 남겨 주세요. 요청 ID가 없어도 문의할 수 있습니다.
문의에 API 키나 전체 인증 헤더를 넣지 마세요

로그인 복구를 마치지 못해 플랫폼 문의를 사용할 수 없다면 이메일로 로그인 지원 요청하기를 따르세요.