メインコンテンツまでスキップ

텍스트 인사이트 API

입력한 텍스트를 요약하여 제목·요약 내용·분류를 반환합니다. 음성 파일 업로드나 STT 요청 없이 사용할 수 있으며, 결과는 비동기로 조회합니다.

음성 전사 결과에서 인사이트를 생성하려면 일반 STT 인사이트를 사용하세요. 텍스트 인사이트는 입력·출력 토큰으로 과금되며, 일반 STT 인사이트의 건수·시간 과금과 구분됩니다.

이용 조건​

  • 이용 권한이 부여된 애플리케이션이 필요합니다. Enterprise 기능 문의를 통해 이용 가능 여부를 확인하세요.
  • 요청 시 인증 가이드에서 발급받은 액세스 토큰을 사용합니다.
  • 무료 사용량으로는 이용할 수 없습니다. 이용 권한이 있는 베이직 플랜 애플리케이션은 결제 카드 등록이 필요합니다.
  • 결과는 요청한 애플리케이션의 토큰으로만 조회할 수 있습니다.

API 목록​

MethodURL설명
POST/v1/insight텍스트 인사이트 생성 요청
GET/v1/insight/{id}처리 상태 및 결과 조회

생성 요청​

POST https://openapi.vito.ai/v1/insight

요청 바디​

Content-Type: application/json

필드타입필수설명
textstring예요약할 텍스트. 최대 175,000자이며 빈 문자열이나 공백만 있는 값은 허용하지 않습니다.
promptstring아니요요약 시 참고할 지시사항. 최대 4,096자입니다.
keywordsstring[]아니요참고할 키워드. 최대 64개, 각 80자 이하, 전체 합계 2,000자 이하입니다.

문자 수는 유니코드 코드 포인트 기준입니다. 문자 수와 별도로 JSON 요청 본문 전체는 2 MiB 이하여야 합니다. 한글 등 멀티바이트 문자는 여러 바이트를 사용하므로 문자 수와 본문 크기는 다를 수 있습니다.

요청 예제​

ACCESS_TOKEN은 발급받은 액세스 토큰으로 바꿉니다.

curl --request POST 'https://openapi.vito.ai/v1/insight' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "고객은 상품 견적서를 요청했습니다. 담당자는 금요일까지 견적서를 전달하고 다음 주 월요일에 다시 연락하기로 했습니다.",
    "prompt": "고객 요청과 담당자의 후속 조치를 정리해 주세요.",
    "keywords": ["견적서", "후속 연락"]
  }'

접수 응답​

정상 접수 시 HTTP 200과 요청 ID를 반환합니다. 이 응답은 처리 완료를 의미하지 않습니다.

{
  "id": "example-insight-id",
  "status": "processing"
}
중복 요청

같은 본문을 다시 POST해도 별도의 ID가 생성됩니다. 완료된 각 요청은 별도로 과금될 수 있습니다. 접수 응답에서 ID를 받았다면 POST를 반복하지 말고 해당 ID로 결과를 조회하세요.

상태 및 결과 조회​

GET https://openapi.vito.ai/v1/insight/{id}
curl 'https://openapi.vito.ai/v1/insight/example-insight-id' \
  --header 'Authorization: Bearer ACCESS_TOKEN'
status의미추가 필드
processing처리 중. 잠시 후 같은 ID로 다시 조회합니다.없음
completed처리 완료results
failed처리 실패error.code

처리 중 응답은 접수 응답과 동일한 id, status 구조입니다. 일시적인 처리 오류는 서버에서 자동 재시도하며, 재시도 대기 중에도 processing을 유지합니다. 같은 ID로 계속 조회하면 되며, 재시도 횟수를 소진하거나 재시도할 수 없는 오류가 발생하면 failed로 바뀝니다.

완료 응답​

results는 인사이트 항목의 배열입니다. 아래 내용은 예시이며, 입력과 지시사항에 따라 달라집니다. 완료 상태에서도 빈 배열이 반환될 수 있습니다.

{
  "id": "example-insight-id",
  "status": "completed",
  "results": [
    {
      "title": "견적서 전달 및 후속 연락",
      "summary": "담당자는 금요일까지 고객에게 견적서를 전달하고 다음 주 월요일에 다시 연락하기로 했습니다.",
      "category": "업무"
    }
  ]
}
필드타입설명
results[].titlestring인사이트 제목
results[].summarystring요약 내용
results[].categorystring인사이트 분류

일반 STT 조회 응답의 results.insight와 달리, 이 API에서는 results 자체가 배열입니다. 토큰 사용량과 청구 금액은 이 API 응답에 포함되지 않습니다.

실패 응답​

처리 실패는 조회 요청의 HTTP 오류와 구분됩니다. HTTP 200 응답의 status와 error.code를 확인하세요.

{
  "id": "example-insight-id",
  "status": "failed",
  "error": {
    "code": "insight_failed"
  }
}

HTTP 오류​

HTTP 상태발생 조건
400잘못된 JSON, 입력 제한 초과, 필수 텍스트 누락, 또는 베이직 플랜의 결제 카드 미등록
401유효한 인증 토큰이 없음
403생성 권한이 없거나 무료 사용량으로 생성 요청
404조회 ID가 없거나 다른 애플리케이션의 요청
410보관 기간이 지난 요청의 본문과 결과가 정리됨
413생성 요청의 JSON 본문이 2 MiB를 초과함
500서버 내부 오류로 요청을 처리하지 못함

HTTP 오류 응답은 code, msg 형식입니다. 예를 들어 정리된 결과를 조회하면 다음 응답을 반환합니다.

{
  "code": "H0007",
  "msg": "swept"
}

결과 보관​

입력 텍스트는 처리가 완료되거나 실패하면 삭제합니다. 결과 본문은 접수 시각으로부터 3일이 지난 뒤 정리 작업의 대상이 됩니다. 3일이 되는 순간 즉시 조회가 막히는 것은 아니며, 실제 정리가 완료된 이후 GET은 HTTP 410을 반환합니다. 필요한 결과는 완료 후 별도로 저장하세요.

토큰 과금​

성공한 요청의 입력·출력 청구 토큰을 기준으로 과금합니다. 단가와 월별 계산 기준은 사용 요금을 확인하세요.