POST/v1/analyses
파일 또는 URL을 제출합니다. 분석과 함께 202를 반환하며 동일한 멱등 요청의 재요청은 200을 반환합니다.
개발자 문서
동영상 하나. API 호출 한 번.
영상을 제출하고 분석을 확인하며 구조화된 결과를 워크플로에 통합하세요.
빠른 시작
기본 URL: https://api.artlint.com. 응답은 JSON이며, 성공 응답은 다음 항목에 담깁니다: data, 실패 응답은 error.
1. 키 만들기
열기 계정 → API 키 Artlint 콘솔에서 다음 키를 만드세요: 전체 접근 권한 키로 영상을 제출하거나, 다음 키를 만드세요: 읽기 전용 키로 결과를 읽습니다. 표시될 때 비밀 값을 복사하고 서버의 비밀 관리 도구에 보관하세요.
보내기 Authorization: Bearer $ARTLINT_API_KEY 를 각 요청에 포함하세요. 키는 워크스페이스 범위에 속하며 앱 로그인에는 사용할 수 없습니다. 세션 쿠키와 로그인 토큰으로는 API 요청을 인증할 수 없습니다.
2. 파일 또는 URL 제출
파일은 JSON을 포함한 multipart form data로 보내세요: options 항목을 먼저 보내고 다음 항목을 보내세요: file 항목:
curl https://api.artlint.com/v1/analyses \
-H "Authorization: Bearer $ARTLINT_API_KEY" \
-H "Idempotency-Key: video-job-8812" \
-F 'options={"max_credits":20,"client_reference":"video-job-8812"};type=application/json' \
-F '[email protected]'URL은 JSON으로 보내세요. 서명된 URL도 지원하며 Artlint가 영상을 다운로드하는 동안 유효해야 합니다.
curl https://api.artlint.com/v1/analyses \
-H "Authorization: Bearer $ARTLINT_API_KEY" \
-H "Idempotency-Key: video-job-8813" \
-H "Content-Type: application/json" \
-d '{"video_url":"https://your-media.example/video.mp4","max_credits":20}'새 요청의 응답: 202 Accepted. 응답에 다음 항목이 포함됩니다: id 시작 부분: ana_, 상태 및 잔액이 포함됩니다. 파일 제출의 초기 상태는 preparing; URL 제출의 초기 상태는 fetching.
3. 분석 진행 확인
curl https://api.artlint.com/v1/analyses/ana_YOUR_ANALYSIS_ID \
-H "Authorization: Bearer $ARTLINT_API_KEY"분석은 다음 상태를 거칩니다: fetching, preparing, 그리고 analyzing. 최종 상태는 completed, completed_with_gaps, failed, 또는 canceled. 다음 항목: stage 필드는 다음을 포함한 더 자세한 진행 상태를 제공합니다: queued 및 finalizing.
완료 후 읽을 항목: summary 를 분석에서 확인하고 다음을 사용하세요: links.findings 에서 발견 사항을 페이지별로 읽을 수 있습니다. 검사 누락 구간과 발견 사항을 함께 검토하세요. 분석이 완료되어도 모든 부분을 평가했다는 뜻은 아닙니다.
현재 개발자 API에서는 전체 보고서 조회와 근거 다운로드 링크가 비활성화되어 다음 응답을 반환합니다: 404. Artlint 앱에서는 보고서와 근거에 계속 접근할 수 있습니다. 발견 사항의 근거 ID는 식별자이며 다운로드 링크가 아닙니다.
안전한 재시도
하나만 사용하세요: Idempotency-Key 를 작업마다 사용하세요. 공백 없는 출력 가능 ASCII 문자 1~200자로 구성합니다. 같은 워크스페이스에서 같은 요청을 반복하면 기존 분석과 함께 다음 응답을 받습니다: 200 OK, 플랜의 동시 작업 한도가 찼을 때도 포함합니다. 같은 키로 다른 옵션을 보내면 다음 응답이 반환됩니다: 409 idempotency_key_reused. 재요청 시 업로드 바이트를 비교하지 않으므로 다른 영상에는 새 키를 사용하세요.
제출 옵션
| 필드 | 필수 | 의미 |
|---|---|---|
max_credits | 필수 | 0~1,000,000,000 사이의 정수입니다. 전체 영상 비용이 이 상한 이내일 때만 검사를 시작합니다. |
client_reference | 선택 | 작업 참조 값입니다. 제어 문자를 제외한 1~128자이며 분석과 웹훅에 포함되어 반환됩니다. |
mode | 선택 | analysis가 기본값이며 유일하게 지원되는 모드입니다. |
analysis_level | 선택 | standard(기본값) 또는 max. Max는 Standard의 모든 검사에 움직임과 물리적 상호작용에 대한 심층 검토를 더합니다. |
filename | 선택 | 1~255바이트이며 슬래시나 제어 문자를 포함할 수 없습니다. 기본값은 파일명 또는 URL의 마지막 경로 구간입니다. |
project_id | 선택 | 키의 워크스페이스에 속한 프로젝트입니다. 기본값은 워크스페이스의 API 프로젝트입니다. |
video_url | JSON 전용 | 공개 호스트의 HTTPS URL입니다. 최대 2,048자이며 사용자 이름이나 비밀번호를 포함할 수 없습니다. |
알 수 없는 필드와 유효하지 않은 값은 다음을 반환합니다: 422 invalid_request, 다음을 포함합니다: error.details.field 로 옵션 이름을 표시합니다. JSON 옵션은 16 KiB로 제한됩니다.
API 참조
아래 모든 엔드포인트에는 API 키가 필요합니다. 읽기에 필요한 권한: api.read; 제출, 취소 및 삭제에는 다음 권한이 필요합니다: api.write.
POST
GET/v1/analyses
List analyses in the key’s workspace, newest first. Filter by client_reference or status. limit is 1–100 (default 50); pass next_cursor as cursor.
GET/v1/analyses/{analysis_id}
상태, 단계, 크레딧, 잔액, 원본 및 결과 링크를 읽습니다.
GET/v1/analyses/{analysis_id}/findings
Read paginated findings. limit is 1–100 (default 50); pass next_cursor as cursor. Optionally filter by category.
POST/v1/analyses/{analysis_id}/cancel
진행 중인 분석을 취소합니다. 202를 반환하며 취소된 검사의 크레딧은 반환됩니다.
DELETE/v1/analyses/{analysis_id}
Delete the video, report, and evidence. Returns 202 with deletion state; subsequent reads return 410 analysis_deleted.
GET/v1/balance
Read the organization’s shared credit balance and configured Standard and Max pricing.
GET/v1/key
현재 키, 접근 권한 및 워크스페이스를 설명합니다. 비밀 값은 숨깁니다.
웹훅으로 결과 받기
엔드포인트를 다음 위치에 등록하세요: 계정 → 웹훅. 분석마다 종료 이벤트는 하나입니다: artlint.analysis.completed, artlint.analysis.failed, 또는 artlint.analysis.canceled, 엔드포인트는 이 이벤트를 구독합니다. 전송이 재시도될 수 있으므로 다음 값으로 중복을 제거하세요: webhook-id.
이벤트를 처리하기 전에 엔드포인트의 서명용 비밀 키로 원본 요청 본문에 대한 Standard Webhooks 서명을 확인하세요. 헤더: webhook-id, webhook-timestamp, 그리고 webhook-signature. 타임스탬프가 최신인지 확인하세요.
완료 이벤트에는 요약, 포함 가능한 가장 심각한 발견 사항, 차감 크레딧 및 잔액이 포함됩니다. 다음 값이 findings_truncated 참이면 API로 전체 발견 사항을 가져오세요. 웹훅을 사용하지 않으면 분석 상태를 폴링할 수도 있습니다.
크레딧 및 결제
앱과 API 분석은 조직의 같은 크레딧 잔액을 사용합니다. 조회할 항목: GET /v1/balance 에서 현재 요금 확인: pricing.standard.credits_per_second 및 pricing.standard.minimum_credits Max 요금은 다음에서 확인하세요 pricing.max. 기본값은 Standard로 초당 1크레딧, 최소 10크레딧입니다. Max는 초당 5크레딧, 최소 150크레딧(30초)입니다. 초 미만은 올림합니다。
Artlint는 준비 후 전체 영상 비용을 계산하며 다음 한도 이내일 때만 시작합니다: max_credits. 그 외에는 다음 상태로 종료됩니다: failed 및 max_credits_exceeded 이며 요금이 차감되지 않습니다. 검사가 시작되면 크레딧을 차감하고 보고서를 제공하지 못하면 반환합니다. 조회할 항목: credits.quoted, credits.charged, 그리고 credits.refunded 를 분석에서 확인하세요.
파일 및 플랜 한도
모든 플랜에서 파일당 최대 2 GiB(2,147,483,648바이트)의 MP4, MOV 및 WebM을 지원합니다. 준비 과정에서 실제 길이와 미디어 호환성을 확인합니다.
| 플랜 | 파일 크기 | 동영상 길이 | 동시 분석 수 |
|---|---|---|---|
| Free | 2 GiB | 1분 | 1 |
| Creator | 2 GiB | 5분 | 1 |
| Pro | 2 GiB | 10분 | 2 |
| Studio | 2 GiB | 30분 | 3 |
동시 분석 한도는 앱에서 시작한 작업을 포함하여 조직의 모든 워크스페이스에서 공유됩니다. 다운로드, 준비 및 대기 중인 검사도 자리를 사용합니다. 취소, 실패 또는 완료 시 자리가 반환됩니다. 크레딧 팩과 무제한 크레딧은 플랜 한도를 늘리지 않으며 만료된 구독은 Free로 돌아갑니다.
키당 한 번에 하나씩 업로드하세요. 기본 요청 한도는 API 프로세스별로 키당 분당 120요청 및 20제출, 워크스페이스당 분당 600요청입니다. 재요청과 거부된 제출도 포함됩니다. 다음을 따르세요: Retry-After 날짜 429 및 재시도 가능한 503 응답을 따르세요. 워크스페이스 저장소와 서비스 용량에 추가 한도가 적용될 수 있습니다.
URL 다운로드는 최대 5번의 리디렉션, 총 30분 및 60초 유휴 제한을 허용합니다. 비공개 호스트와 HTTPS가 아닌 원본은 거부됩니다.
오류 처리
거부된 요청은 오류 객체를 반환합니다:
{
"error": {
"code": "invalid_request",
"message": "…",
"details": { "field": "max_credits" },
"request_id": "…"
}
}요청 오류
| HTTP 상태 | 오류 코드 | 의미 및 해결 방법 |
|---|---|---|
| 401 | unauthorized | 유효한 API 키를 사용하세요. 키가 없거나 만료, 취소 또는 무효 상태입니다. |
| 403 | insufficient_scope | 분석을 제출, 취소 또는 삭제하는 요청에는 전체 접근 키를 사용하세요. |
| 403 | developer_api_disabled | 이 설치 환경에서는 API 접근이 활성화되지 않았습니다. |
| 409 | idempotency_key_reused | 옵션이나 영상이 바뀌면 새 작업 키를 사용하세요. |
| 413 | file_too_large | 업로드가 2 GiB를 초과합니다. 더 작은 파일을 제출하세요. |
| 422 | invalid_request | details.field에서 잘못된 옵션을 확인하세요. 멀티파트 업로드에서는 file보다 options를 먼저 보내세요. |
| 429 | plan_concurrency_limit | 분석 가능 자리가 생길 때까지 기다리세요. details.plan_limits를 확인하고 Retry-After를 준수하세요. |
| 429 | too_many_active_analyses | 워크스페이스 서비스 한도에 도달했습니다. 처리 용량이 확보되면 다시 시도하세요. |
분석 실패
접수된 분석도 비동기적으로 실패할 수 있습니다. 확인할 필드: error 필드 또는 실패 웹훅을 확인하세요.
| 오류 코드 | 의미 및 해결 방법 |
|---|---|
source_too_large | URL에서 다운로드한 영상이 2 GiB를 초과합니다. 더 작은 원본 파일을 사용하세요. |
plan_duration_limit | 접수된 영상이 요금제의 길이 한도를 초과합니다. 영상을 줄이거나 한도가 더 높은 요금제를 선택하세요. |
credits_insufficient | 검사가 시작되지 않았고 요금도 청구되지 않았습니다. 크레딧을 추가한 후 다시 시도하세요. |
max_credits_exceeded | 검사가 시작되지 않았고 요금도 청구되지 않았습니다. 클립 비용을 충당하도록 max_credits를 높이세요. |
앱을 사용하고 싶으신가요?
로그인하고 동영상 목록을 여세요. 선택할 항목: 동영상 분석, MP4, MOV 또는 WebM 파일을 선택하세요. 최대 파일 크기는 2 GiB입니다. 동영상 최대 길이는 Free 1분, Creator 5분, Pro 10분, Studio 30분입니다. 검사에 필요한 크레딧도 있어야 합니다. 분석 완료 후 발견 사항, 원본 프레임 근거 및 검사 누락 구간을 확인하세요. 자세한 내용은 데이터 및 개인정보 에서 처리 및 보관 내용을 확인하세요.