API 참조

모든 엔드포인트와 그 요청 및 응답 형태. 모든 경로는 https://sketchie.ai/api 를 기준으로 한 상대 경로입니다.

규약

모든 /v1/* 엔드포인트는 Authorization: Bearer sk_... 헤더가 필요합니다. 오류는 error 플래그와 message가 있는 JSON으로 돌아옵니다:

오류 응답

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

생성 엔드포인트는 분당 20개 요청으로 속도 제한됩니다. 다른 모든 엔드포인트는 분당 200개 제한을 공유합니다.

설명 영상 생성하기

POST https://sketchie.ai/api/v1/explainer

생성을 시작하고 대기열에 들어간 레코드와 함께 202 Accepted를 반환합니다. ready가 될 때까지 설명 영상 가져오기를 폴링하세요.

요청 본문

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

필드	타입	비고
`input`	string	설명할 내용. 짧은 프롬프트 또는 전체 문서 텍스트. `source` 또는 `sceneGraph`가 없으면 필수. 별칭: `prompt`.
`length`	string or number	`"M:SS"`(`"0:30"`, `"1:00"`) 또는 초 단위의 목표 길이. 30의 양의 배수, 최대 360. 자동 길이를 원하면 생략하세요. 별칭: `lengthSeconds`(숫자).
`voice`	string	선택 사항. 음성 참조. 기본값은 표준 내레이터(Nora). 음성 참조.
`language`	string	선택 사항. 지원되는 언어 코드(기본값 `en`). 언어 참조.
`aspect`	string	선택 사항. `16:9`(기본값), `9:16` 또는 `1:1`.
`source`	string	선택 사항. 설명 영상으로 만들 문서, 기사 또는 스크립트. 있으면 `input`은 선택적 안내가 됩니다.
`preset`	string	선택적 그리기 스타일: `marker`(기본값), `chalkboard`, `pencil`, `blueprint`, `crayon`, `clean`.
`fillMode`	string	선택적 리빌 채우기 기법: `A`, `B`, `C`(기본값) 또는 `D`.
`sceneGraph`	object	선택 사항. 미리 작성된 scene graph. 워커는 그래프 생성을 건너뛰고 직접 렌더링하지만, 이 엔드포인트는 여전히 새 설명 영상을 생성하고 호출자의 일반 무료 허용량 또는 유료 플랜 쿼터를 소비합니다. 기존 설명 영상을 편집하려면 설명 영상 편집을 사용하세요.

설명 영상 레코드를 반환합니다: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl(준비 전까지 null), sceneGraph(생성 전까지 null). source 없는 빈 input, 잘못된 length, 또는 유효하지 않은 aspect, preset, fillMode, language의 경우 400이 돌아옵니다.

설명 영상 가져오기

GET https://sketchie.ai/api/v1/explainer/:id

전체 레코드를 반환합니다: 현재 status, ready가 되면 videoUrl, 편집 가능한 sceneGraph, 버전 히스토리(versions), 헤드 버전의 장면 chunks. 존재하지 않는 id는 404를 반환합니다.

설명 영상 목록

GET https://sketchie.ai/api/v1/explainer?limit=50

호출 키의 설명 영상을 최신순으로 나열합니다. 키 소유자로 범위가 지정됩니다. limit은 1~100으로 제한됩니다(기본값 50). 경량 요약을 반환합니다(scene graph나 버전 없음). 전체 레코드에는 설명 영상 가져오기를 사용하세요.

설명 영상 편집하기

POST https://sketchie.ai/api/v1/explainer/:id/edit

편집 가능성의 쐐기. 평이한 언어 지시를 타깃 재렌더링으로 바꿉니다. 영향을 받는 장면만 다시 렌더링되어 새 버전이 생성됩니다. 대기열에 들어간 버전과 함께 202를 반환합니다. 헤드 버전이 ready가 될 때까지 설명 영상 가져오기를 폴링하세요. 이는 기존 영상에 추가되므로 또 다른 무료 영상 생성 슬롯을 소비하지 않습니다. 각 영상의 첫 재렌더링은 무료입니다. 이후 재렌더링은 유료 플랜 분을 사용하며, 무료 계정은 플랜 시작을 요청받습니다. 설명 영상은 이미 ready 상태여야 합니다(그렇지 않으면 409).

요청 본문

{ "instruction": "Make the title scene shorter and warmer" }

버전으로 되돌리기

POST https://sketchie.ai/api/v1/explainer/:id/revert

헤드를 이전 준비된 버전으로 다시 가리키고 그 그래프와 영상을 레코드에 반영합니다. 대상은 영상이 있는 ready 버전이어야 합니다(그렇지 않으면 409).

요청 본문

{ "versionId": "..." }

라이브 상태 스트림

GET https://sketchie.ai/api/v1/explainer/events

Server-Sent Events 스트림(text/event-stream). 연결 하나를 열면 어느 설명 영상이든 모든 상태 전환이 event: status 프레임으로 도착하므로, 폴링 대신 워커가 끝나는 순간 "영상 준비됨" 상태를 업데이트할 수 있습니다. 스트림은 키 소유자로 범위가 지정됩니다.

음성

GET https://sketchie.ai/api/v1/voices

내레이션 음성 카탈로그. 선택적 ?language=<code>는 해당 언어를 모국어로 하는 음성으로 필터링합니다. voices(각각 친숙한 name, voice로 전달할 id, language, isDefault, 재생 가능한 preview_url)와 전역 default를 반환합니다. 음성 참조.

언어

GET https://sketchie.ai/api/v1/languages

지원되는 내레이션 언어를 { code, label, native }로. 모든 code는 생성 시 유효한 language입니다. 언어 참조.

계정 상태

GET https://sketchie.ai/api/v1/account/state

videosGenerated(누적), 계정 image, isAdmin을 반환합니다. 인증이 필요합니다.

청구 상태

GET https://sketchie.ai/api/v1/billing/status

인증이 필요하며 무료 및 유료 계정 모두에 200을 반환합니다. 무료 계정은 plan: "free"와 videoAllowance, videosUsed, videosRemaining을 반환합니다. 유료 계정은 추가로 planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining, bonusMinutes를 반환합니다.

런타임 구성 및 상태

GET https://sketchie.ai/api/config

공개. { "authEnforced": true }를 반환합니다. 활성 확인은 GET /health에 있습니다.