사용량과 한도

노트

모든 예제는 https://video.pyler.ai와 $VUF_API_KEY에 담긴 API 키를 사용합니다. 인증을 참고하세요.

사용 한도 확인

GET /api/v1/usage는 API 키를 소유한 조직의 현재 사용 한도와 남은 허용량을 반환합니다.

cURL
Python

curl -s https://video.pyler.ai/api/v1/usage \
  -H "Authorization: Bearer $VUF_API_KEY"

import os, requests

BASE = "https://video.pyler.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VUF_API_KEY']}"}

usage = requests.get(f"{BASE}/usage", headers=HEADERS).json()
if usage["remaining"]["videos"] == 0:
    print("video quota exhausted; new submissions will be refused")

Response (200)
{
  "plan": "trial",
  "videos":  { "used": 12,  "limit": 100 },
  "minutes": { "used": 340, "limit": 1000 },
  "ads":     { "used": 2,   "limit": 20 },
  "summaries": { "used": 5, "limit": 30 },
  "remaining": { "videos": 88, "minutes": 660, "ads": 18, "summaries": 25 }
}

planstring

조직의 사용 한도 플랜 이름입니다.

videosUsage

플랜에 집계된 영상 수입니다. used와 limit을 담습니다.

minutesUsage

플랜에 집계된 영상 분량(분)입니다. used와 limit을 담습니다.

adsUsage

플랜에 집계된 광고 소재 수입니다. used와 limit을 담습니다.

summariesUsage

플랜에 집계된 맞춤 요약 요청 수입니다. used와 limit을 담습니다. videos와 따로 집계됩니다.

remainingRemaining

아직 사용할 수 있는 videos, minutes, ads, summaries입니다.

상태	의미
`404`	이 조직에 아직 사용 한도 플랜이 할당되지 않았습니다. 예를 들어 계정을 프로비저닝하는 중일 수 있습니다. 계속되면 지원팀에 문의하세요.
`503`	사용 한도 데이터 저장소를 일시적으로 사용할 수 없습니다. 재시도하세요.

스펙에 명시된 사용 한도 차감 방식은 다음과 같습니다.

맞춤 요약 요청은 rejected로 끝나더라도 videos가 아니라 summaries에 1건으로 집계됩니다. failed로 끝난 요청, 또는 영상이 삭제될 때 아직 queued 상태인 요청은 사용 한도에 반환됩니다. 요약 사용 한도가 소진되면 POST는 code: quota_exceeded_summaries와 함께 422를 응답하며 아무것도 생성하지 않습니다.
플랜에서 더 이상 MRSS를 허용하지 않는 MRSS 피드는 plan_blocked: true로 표시됩니다. 다시 활성화하면 code: mrss.disabled와 함께 422를 반환합니다.

요청별 제한

OpenAPI 스펙에 선언된 상한과 기본값입니다. 범위를 벗어난 값은 스키마 검증에 실패해 422를 반환합니다.

색인 생성

엔드포인트	한도
`GET /api/v1/videos`	`limit` 1~100, 기본값 50. 커서 페이지네이션.
`GET /api/v1/videos/{video_id}`	`scene_limit` 1~200, 기본값 50; `scene_offset` ≥ 0.
`GET /api/v1/videos/{video_id}/scenes`	`limit` 1~200, 기본값 50; `offset` ≥ 0.
`GET /api/v1/videos/{video_id}/scenes/stream`	서버 측 최대 스트림 지속 시간이 있으며, 도달하면 스트림이 `{"event": "timeout"}`으로 끝납니다. 다시 연결하면 새 스냅숏을 받습니다.
`POST /api/v1/videos/batch`	`items` 최대 500행; `total` 0~500; 행마다 `url` ≤ 2048자, `title` ≤ 500자. `items`가 너무 길면 `422` 목록 형식을 반환합니다.
`POST /api/v1/videos/batch/upload`	요청당 약 10개 이하 파일을 권장합니다. 안전 장치로, 요청당 그리고 재사용한 `batch_id` 전체 기준으로 500개를 넘으면 `413`을 반환합니다.
`POST /api/v1/videos/batch/upload-sheet`	시트 크기 상한 10 MB 또는 유효한 URL 500행을 넘으면 `413`. 데이터 10000행 초과, 열이 너무 많은 경우, 압축 해제 크기 상한을 넘는 경우 `422`. 제외된 행은 최대 100개까지 `rejected_rows`에 나열합니다.
`POST /api/v1/videos/{video_id}/custom-summaries`	`instructions` ≤ 2000자; `cast` ≤ 100명, 각 `name` 1~200자, `aliases` ≤ 20개; `language` ≤ 35자, 언어 태그 패턴.
`GET /api/v1/videos/{video_id}/custom-summaries`	`limit` 1~100, 기본값 50. 커서 페이지네이션.
`PATCH /api/v1/mrss-feeds/{feed_id}`	`poll_interval_s`는 3600, 21600, 86400 중 하나; `label` ≤ 200자, 제어 문자 불가. 빈 본문은 `422`.
`GET /api/v1/mrss-feeds/{feed_id}/items`	`limit` 1~200, 기본값 50; `offset` ≥ 0.

검색

엔드포인트	한도
`POST /api/v1/search`, `POST /api/v1/search/deep`	`k` 1~~100, 기본값 20; `scene_pool` 10~~200, 기본값 60; `min_relevance` 0~10, 기본값 3. `video_id`는 UUID여야 합니다. 커서 없음: 결과는 열마다 `k`개로 제한됩니다.
`POST /api/v1/search/multimodal`	`k` 기본값 20; `scene_pool` 기본값 60.

엔드포인트	한도
`POST /api/v1/ads/match`	`per_query_k` 2~~400, 기본값 100; `max_candidates` 5~~400, 기본값 100; `max_per_video` 1~50, 기본값 10.

라이브

엔드포인트	한도
`POST /api/v1/live/streams`, `PATCH /api/v1/live/streams/{stream_id}`	`segment_n` 1~~60, 기본값 8; `poll_interval_s` 1~~3600초, 기본값 6.

호출 속도 제한

처리량은 위의 조직 사용 한도, 요청별 상한, 배치·시트 업로드의 크기 안전 장치(413)로 제한됩니다. 너무 큰 요청은 통째로 거부되며, 속도가 제한되거나 일부만 처리되지 않습니다.

조직별로 요청 한도가 추가로 적용될 수 있으며, 검색·매칭·심사 뒤의 분석 단계는 고객 간에 처리량을 공유합니다. 429 Too Many Requests는 다른 일시적 오류와 똑같이 처리하도록 클라이언트를 만드세요. 백오프하고(Retry-After 헤더가 있으면 따름) 전체 마감 시간 안에서 재시도합니다. 폴링 간격은 몇 초로 유지하고, 촘촘한 폴링 루프보다 스트리밍 엔드포인트를 쓰고, 영상마다 요청을 하나씩 보내지 말고 배치로 제출하세요.

타임아웃과 재시도

아래 안내는 브랜드 세이프티 심사를 기준으로 작성했지만, 요청이 수락된 뒤 작업을 수행하는 모든 호출에 적용됩니다.

타임아웃은 실패가 아니라 결과를 알 수 없는 상태입니다. API가 요청을 수락하면 연결이 유지되는지와 관계없이 끝까지 실행하고 결과를 저장합니다. 잃는 것은 응답뿐입니다. 타임아웃이 나면 작업이 수행되지 않았다고 가정하지 말고, 다시 제출하기 전에 결과를 조회하세요.

권장 클라이언트 타임아웃: 120초. 대부분의 호출은 몇 초 안에 반환됩니다. 이 상한은 일반적인 경우가 아니라 드문 지연에 대비한 값입니다.

5분 넘게 올려도 효과가 없습니다. 5분 동안 데이터를 내보내지 않은 요청은 504로 닫힙니다. 계속 줄을 내보내는 스트리밍 응답은 더 오래 실행될 수 있지만, 조용한 요청은 5분 시점에 끝납니다. 스트리밍 엔드포인트(/api/v1/ads/match, /api/v1/videos/{video_id}/scenes/stream, /api/v1/live/streams/{stream_id}/events, 그리고 judge: "text"를 지정한 /api/v1/search)는 NDJSON을 반환합니다. 데이터가 도착하는 대로 한 줄씩 파싱하세요.

백오프. 전체 마감 시간 안에서 한두 번 재시도하면 충분합니다. 재시도는 다른 요청에 쓰일 처리량을 차지하고 요청 한도에도 집계되므로, 습관적으로 하지 말고 의도적으로 하세요.

재시도해도 안전한 경우

상황	재시도	이유
모든 엔드포인트의 `500`	예	"업스트림 서비스 오류, 대개 재시도해도 안전함"으로 문서화되어 있습니다.
`GET /api/v1/usage`의 `503`	예	사용 한도 데이터 저장소를 일시적으로 사용할 수 없습니다.
`POST /api/v1/videos/{video_id}/custom-summaries`의 `503`	예	요청이 큐에 들어가지 않았고 아무것도 생성되지 않습니다. 재시도할 때마다 새 요청이 만들어집니다.
`POST /api/v1/videos`(URL) 타임아웃	예	아직 색인 생성 중인 URL을 다시 제출하면 두 번째 파이프라인을 시작하지 않고 기존 `video_id` / `job_id`를 `created: false`와 함께 반환합니다.
`POST /api/v1/videos/batch`(`kind: "url"`) 타임아웃	예, 주의해서	URL이 이미 색인 생성 중인 행은 기존 작업에 연결됩니다(`created: false`). `dispatch_failed`를 포함한 `failed` 행은 다시 제출하는 것이 원칙입니다. 먼저 `GET /api/v1/videos/{video_id}`로 확인하세요.
`POST /api/v1/videos/upload` 또는 `/batch/upload` 타임아웃	무작정 하지 않음	업로드에는 자연스러운 중복 제거 키가 없습니다. 먼저 `GET /api/v1/videos/batch/{batch_id}`를 폴링하고 아직 없는 파일만 다시 보내세요. `error`가 `dispatch_failed`인 항목은 건너뛰세요. 영상 행이 이미 커밋되어 있어 다시 보내면 파일이 두 번 색인됩니다.
엣지의 `504`	먼저 조회	작업이 완료되었을 수 있습니다. 다시 보내기 전에 작업, 영상, 배치, 심사 결과를 확인하세요.
`409`, `413`, `422`	아니요	요청 자체가 잘못되었습니다. 요청을 수정하세요(아래 참고).

과대 요청과 잘못된 요청

413 Payload too large

엔드포인트	발생 조건	해결 방법
`POST /api/v1/videos/batch/upload`	요청당 그리고 재사용한 `batch_id` 전체 기준으로 파일이 500개를 넘었습니다.	약 10개 파일 단위 요청으로 나누세요.
`POST /api/v1/videos/batch/upload-sheet`	시트가 10 MB를 넘거나, 유효한 URL 행이 배치 하나가 받을 수 있는 수(현재 500)를 넘었습니다.	여러 시트로 나누세요.

422 Unprocessable

본문 형태가 두 가지이므로, 읽기 전에 detail의 타입으로 분기하세요.

봉투 형식: {"detail": "message", "code": "stable.code"}. code는 실패에 고정된 기계 판독용 사유가 있을 때만 있습니다. 이 가이드의 예: quota_exceeded_summaries, custom_summary_no_base_summary, custom_summary_no_org, mrss.bad_interval, mrss.bad_label, mrss.bad_status, mrss.bad_index_status, mrss.disabled.
스키마 검증 목록 형식: {"detail": [{"loc": [...], "msg": "..."}]}이며 code가 없습니다. 본문을 선언한 모든 엔드포인트가 반환할 수 있습니다. 대표적인 경우는 POST /api/v1/videos/batch에 너무 긴 items 배열을 보낼 때입니다. 빈 객체로 PATCH /api/v1/mrss-feeds/{feed_id}를 호출해도 이 형식을 반환합니다.

시트 업로드는 형제 키를 하나 더 붙입니다. code가 no_valid_urls이면 413 / 422 본문에 파싱 중 제외된 행 수인 rejected도 담깁니다(어떤 배치에도 기록되지 않음).

422 on upload-sheet
{ "detail": "no valid url rows in sheet", "code": "no_valid_urls", "rejected": 17 }

문서화된 그 밖의 422 발생 조건은 다음과 같습니다.

잘못된 형식의 reindex_run_id UUID, 또는 UTC 오프셋이 없는 reindexed_since로 GET /api/v1/videos를 호출한 경우.
매니페스트에 접근할 수 없거나 유효한 플레이리스트가 아닌 새 url로 POST /api/v1/live/streams 또는 PATCH를 호출한 경우.
.csv / .xlsx가 아니거나, url 열이 없거나, 형식이 잘못되었거나 손상되었거나, 유효한 URL 행이 없거나, 데이터 10000행 또는 열 수 / 압축 해제 크기 상한을 넘는 파일로 POST /api/v1/videos/batch/upload-sheet를 호출한 경우.

과대 오류 본문

게이트웨이가 직접 만드는 code가 하나 있습니다. upstream_error_too_large는 하위 서비스의 오류 본문이 너무 커서 전달할 수 없었다는 뜻입니다. 상태 코드는 유지되지만 항목별 사유는 사라집니다. 항목 수를 줄여 재시도하면 상세 응답을 받을 수 있습니다.

전체 형식과 공통 상태 표는 오류를 참고하세요.

다음 단계

영상 색인 생성

배치 복구 규칙을 맥락과 함께 설명합니다.

Usage API 레퍼런스

GET /api/v1/usage의 스키마입니다.

사용 한도 확인​

요청별 제한​

색인 생성​

검색​

광고​

라이브​

호출 속도 제한​

타임아웃과 재시도​

재시도해도 안전한 경우​

과대 요청과 잘못된 요청​

413 Payload too large​

422 Unprocessable​

과대 오류 본문​

다음 단계​