본문으로 건너뛰기
VIDIA고수의 노하우로 만드는 영상

도움말

개발자 가이드

API·MCP로 공개 검색부터 상담·견적·설계도·대표 장면 승인, 초안·정산·알림 설정까지 이어 쓰는 방법을 안내합니다. 사진은 실제 화면이고, 누르면 크게 볼 수 있어요.

1. API·MCP 로 연동하기

API 키 화면
API 키
  1. 왼쪽 메뉴 맨 아래 '더 보기'를 열고 'API 키'에서 키를 만들어요(최대 10개). 권한은 '조회·견적만'(포인트를 쓰지 않음), '제작 시작 허용'(견적대로 제작 시작·취소, 예산만큼 포인트를 먼저 잡아 둠), '시험용'(포인트를 쓰지 않고 연동만 시험) 중에 골라요. 키는 만들 때 한 번만 보이니 바로 복사해 두세요.
  2. '제작 시작 허용' 키에는 하루 제작 상한(최근 24시간 편수)을 정해요. 프로그램이 잘못 반복 호출해도 그 이상 제작하지 않아요. '안전장치(선택)'를 펼치면 한 편 예산 상한·하루 예산 상한(포인트)과 이 키를 쓸 수 있는 IP 를 더 정할 수 있어요.
  3. REST API: 모든 요청에 Authorization: Bearer <API 키> 헤더를 붙여요. 순서는 GET /api/v1/packages(패키지 찾기) → GET /api/v1/packages/<slug>(입력 칸) → POST /api/v1/quotes(견적, 무료) → POST /api/v1/runs(quote_id·budget·idempotency_key·confirm: true 로 제작 시작) → GET /api/v1/runs/<번호>(진행 확인) → GET /api/v1/runs/<번호>/files(결과물과 1시간짜리 다운로드 링크)예요. 링크로 받을 때도 같은 키를 Authorization: Bearer 헤더로 함께 보내세요(예: curl -H "Authorization: Bearer $VIDIA_API_KEY" -o video.mp4 "<링크>"). 지금은 유예 기간이라 키 없이도 받히지만 Vidia-Deprecation 경고가 붙고, 유예 기간이 끝나면 키 없는 요청은 거절돼요. 다른 회원의 키로는 받을 수 없어요. SDK vidia-api 는 1.2.1 부터 키를 함께 보내요.
  4. 제작이 멈추면(예산 부족·선택 대기·오류) GET /api/v1/runs/<번호> 의 pending(멈춘 사정)과 actions(지금 보낼 수 있는 동작)를 보고 POST /api/v1/runs/<번호>/actions 로 풀어요. 예: { "action": "add_budget", "add": 2000, "idempotency_key": "...", "confirm": true }(예산 추가), { "action": "retry" }(다시 시도), { "action": "finish" }(지금까지 만든 것으로 마치기). 완성되면 files 응답의 upload 에 유튜브에 올릴 제목 후보·설명란·태그·고정 댓글·업로드 판정이 함께 와요.
  5. 처음 연동할 때는 시험용 키(vd_test_ 로 시작)를 쓰세요. 같은 요청을 그대로 보내면 실제 영상은 만들지 않고 약 40초 뒤 견본 결과가 와요. 제작 시작에 "test_scenario": "fail"(오류)·"budget"(예산 부족)·"review"(품질 미달)를 넣으면 멈춘 상황과 그 뒤 처리까지 시험할 수 있어요.
  6. 웹훅: 같은 화면의 '새 웹훅'에 https 주소를 등록하면 제작이 완성·실패·취소되거나 확인이 필요할 때 그 주소로 알려 줘요(상태를 계속 물어볼 필요가 없어요). 만들 때 한 번 보이는 비밀값으로 Vidia-Signature 헤더를 확인하고, '시험 전송'으로 주소가 잘 받는지 볼 수 있어요.
  7. 주제를 정하기 어려우면 GET /api/v1/packages/<slug>/topic-idea 로 그 패키지에 맞는 추천 주제를 받고, GET /api/v1/packages/<slug>/results 로 그 패키지로 만든 공개 결과물을 미리 볼 수 있어요. GET /api/v1/usage 는 저장공간·진행 중인 제작 수·이 키로 오늘 더 시작할 수 있는 제작 수를, GET /api/v1/points/history 는 포인트 내역을 알려 줘요.
  8. 진행 확인을 여러 번 부르는 대신 GET /api/v1/runs/<번호>?wait=50 처럼 wait(초, 최대 50)를 붙이면 제작이 끝나거나 멈출 때까지 기다렸다가 답해요. 전체 경로와 입력 모양은 GET /api/v1/openapi.json(OpenAPI 명세)에 있어요.
  9. 사진·영상을 넣는 입력 칸(종류 asset)에는 자료실 파일 번호를 넣어요. 파일은 POST /api/v1/assets 로 올리고('제작 시작 허용' 키), GET /api/v1/assets 로 목록을 봐요. 키를 넣기 어려운 곳에서는 POST /api/v1/assets/upload-link 로 15분짜리 업로드 주소를 받아 그 주소로 올리면 돼요(주소 하나로 파일 하나만 — 올리고 나면 그 주소는 끝나요).
  10. 여러 편을 한 번에 만들려면 POST /api/v1/batch/quotes 로 견적을 묶어 받고 POST /api/v1/batch/runs 로 묶어 시작해요(한 번에 10건까지, 결과는 건별로 와요). 예전 제작과 같은 내용으로 다시 만들 때는 GET /api/v1/runs/<번호>/input 으로 넣었던 입력값을 받아 그대로 견적에 넣어요. 완성 뒤에는 POST /api/v1/runs/<번호>/thumbnail 로 대표 썸네일을 바꾸고 POST /api/v1/runs/<번호>/showcase 로 쇼케이스에 공개할 수 있어요.
  11. 자주 쓰는 편의 기능: GET /api/v1/runs?completed=true&format=shorts&q=<제목>&sort=completed 로 완성된 것만 골라 보고, GET /api/v1/runs/status?ids=101,102,103 으로 여러 제작의 상태를 한 번에, POST /api/v1/batch/files 로 여러 편의 다운로드 링크를 한 번에(10편까지), GET /api/v1/runs/<번호>/upload-kit 로 업로드 키트만 받아요. 실패·취소한 제작은 POST /api/v1/runs/<번호>/remake-quote 로 같은 내용의 새 견적을 받고, POST /api/v1/runs/quote-and-start 는 견적을 받아 정한 최대 예산(max_budget) 안이면 바로 시작해요(confirm: true 필수, 넘으면 시작하지 않고 견적만 돌려줘요). 요청이 너무 많거나 하루 상한에 닿으면 429 와 함께 Retry-After(기다릴 초)가 와요.
  12. MCP: Claude·Cursor·Codex 같은 AI 에이전트에 원격 주소 https://vidia.kr/mcp 와 같은 헤더를 넣거나, npx -y vidia-mcp 를 VIDIA_API_KEY 환경변수와 함께 등록하면 에이전트가 견적·제작·다운로드를 대신 해 줘요(예: claude mcp add vidia -e VIDIA_API_KEY=<API 키> -- npx -y vidia-mcp).
  13. 코드에서는 npm 패키지 vidia-api 를 쓰면 견적·제작·완성 대기·다운로드를 몇 줄로 할 수 있어요.
  14. 견적 전에 POST /api/v1/member-briefs/check 또는 vidia_check_counsel로 필수 확인을 보세요. COUNSEL_REQUIRED가 오면 설정을 고치거나 사용자가 직접 선택한 확인 기록을 member_brief.counsel에 넣어요. 회원 요구와 설정은 견적·시작에 똑같이 보내세요.
  15. 설계도는 vidia_get_blueprint → vidia_edit_blueprint 또는 vidia_refine_blueprint → vidia_quote_blueprint → vidia_approve_blueprint 순서로 이어져요. AI 다듬기는 먼저 vidia_quote_blueprint_refine으로 금액을 확인해요. 대표 장면은 제작 화면에서 확인한 뒤 vidia_quote_sample_review로 본편·수정 견적을 새로 받고 vidia_approve_sample_review로 승인해요.
  16. 계정 초안은 /api/v1/run-drafts에서 이어 쓰고 개정 번호 revision으로 다른 기기의 수정을 보호해요. /api/v1/search는 공개 자료만 검색하고, /api/v1/status는 서비스 상태를 보여 줘요. 정산은 /api/v1/runs/<번호>/settlement, 제작 완료 알림은 /api/v1/notifications/run-complete에서 확인해요. 필수 결제·보안 알림은 이 설정으로 꺼지지 않아요.
  17. 마켓 가격은 부가세 포함 결제액이에요. 공개 추천 패키지만 연결하며 원본 제작 정보를 공개하지 않아요. 시험용 키는 실제 설계도·초안·알림 설정을 바꾸거나 상담을 실행하지 않아요. 새 기능의 입력 이름은 공개 OpenAPI 명세와 MCP 도구 목록에서 확인하세요.

팁 제작 시작·AI 다듬기·대표 장면 수정·본편 제작은 비용이 들 수 있어요. 새 견적 금액을 보여 주고 동의를 받은 뒤에만 실행하세요. 한 편·하루 예산 상한은 API와 MCP에도 적용돼요.

팁 선택이 필요한 순간(예산 승인·확인 대기·오류)은 진행 확인 응답의 actions 로 바로 풀 수 있고, 웹의 프로젝트 화면에서도 이어 갈 수 있어요. 응답에 그 주소가 함께 와요.

팁 쓰지 않는 키나 새어 나간 것 같은 키는 바로 '폐기'하세요. 이미 시작한 제작은 그대로 진행돼요.

2. 로그인으로 AI 앱 연결하기

앱 연결 동의 화면 화면
앱 연결 동의 화면
  1. OAuth 를 지원하는 AI 앱(원격 MCP 커넥터)에는 API 키를 붙여 넣지 않아도 돼요. 앱의 MCP 서버 주소 칸에 https://vidia.kr/mcp 만 넣으면 비디아 로그인 화면이 열려요.
  2. 로그인하면 이 동의 화면이 나와요. 앱 이름은 앱이 스스로 적은 것이라 '확인되지 않은 앱'으로 표시돼요 — 강조된 칸의 돌아갈 주소가 지금 쓰는 앱의 주소인지 꼭 확인하고, 허용할 일을 골라요 — '조회·견적만'(포인트를 쓰지 않음) 또는 '제작 시작 허용'(하루 제작 상한을 함께 정해요).
  3. '연결 허용'을 누르면 앱으로 돌아가 바로 쓸 수 있어요. 직접 시작한 연결이 아니면 '거절'을 누르세요.
  4. 연결한 앱은 'API 키' 화면의 '연결한 앱'에 나와요. '연결 끊기'를 누르면 그 앱은 바로 쓸 수 없게 돼요.

팁 앱에 준 권한을 바꾸려면 앱에서 다시 연결하면 돼요. 같은 앱은 연결이 하나로 유지되고 새로 고른 권한으로 바뀌어요.

팁 제작·AI 다듬기·본편 승인은 견적 금액 확인을 거쳐요. 제작 시작 허용 권한에는 초안과 제작 완료 알림 설정 변경도 포함돼요.

더 알아보기