AI 동영상 API 고르는 법: 비동기 작업, 웹훅, 환불

AI 동영상 API를 고르는 일은 이미지 API를 고르는 것과 달라요. 동영상 렌더는 몇 초가 아니라 몇 분이 걸리기 때문에, 일주일 중 얼마나 많은 시간을 잡아먹을지는 프레임 품질이 아니라 연동 구조가 결정해요. 작업 모델을 잘못 잡으면 나중에 큐, 재시도, 과금 정산까지 다시 짜야 해요. 첫 요청을 작성하기 전에 확인해야 할 일곱 가지를 eroq의 구조를 예시 삼아 정리했어요.

1. 블로킹 호출이 아닌 비동기 작업

동영상이 나올 때까지 기다리는 블로킹 HTTP 요청은 편리함으로 위장한 함정이에요. 로드 밸런서, 서버리스 플랫폼, CDN은 모두 긴 렌더 시간보다 훨씬 짧은 요청 제한 시간을 두고 있어요. 그래서 블로킹 API는 테스트에서는 잘 돌다가, 프로덕션에서 렌더가 평소보다 오래 걸리는 바로 그 순간에 죽어 버려요.

올바른 구조는 작업(job)이에요. eroq에서는 POST /v1/videos/generations가 즉시 작업 ID를 반환하고, 이후 GET /v1/videos/generations/{id}를 폴링하거나 웹훅을 기다리면 돼요. 전체 레퍼런스는 /docs/video에 있어요.

# 1. submit
curl -X POST https://eroq.ai/v1/videos/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-lite",
    "prompt": "A courier weaves a bicycle between stopped cars on a wet avenue at dusk, headlights smearing across the frame. Tracking shot, 35mm film, anamorphic lens, neon noir palette, dynamic tempo.",
    "seconds": 5,
    "aspect": "9:16"
  }'

# 2. poll (or skip this and use a webhook)
curl https://eroq.ai/v1/videos/generations/JOB_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"

다른 서비스에서 확인할 점은 동영상 엔드포인트가 정말 비동기인지, 그리고 프로세스가 재시작된 뒤 작업을 복구할 수 있는 목록 엔드포인트가 있는지예요. 렌더의 유일한 기록이 잃어버린 응답뿐이라면, 렌더도 함께 잃게 돼요.

2. 실제로 검증할 수 있는 웹훅

처음에는 폴링으로 충분하지만 규모가 커지면 낭비예요. 웹훅은 서명된 채로 도착해야 하고, 서명 방식은 이미 구현해 본 적 있는 방식이어야 해요.

eroq는 Stripe 스타일의 서명 헤더와 함께 video.generation.succeeded와 video.generation.failed를 보내고, 페이로드에는 인라인 base64 대신 CDN URL이 담겨요. 이게 중요한 이유는, 수 MB짜리 JSON 바디는 언젠가 스택 어딘가를 망가뜨리기 때문이에요.

어떤 업체든 세 가지를 물어보세요. 페이로드가 서명되는지, 서명 대상에 리플레이 방지 시간 창이 들어 있는지, 바디에 URL이 담기는지 바이트가 담기는지. 답은 2026년 9월 기준 각 업체 문서에서 직접 확인하세요.

3. 렌더가 실패하면 어떻게 되나

진짜 플랫폼과 단순 래퍼를 가르는 기준이 바로 이것인데, 가격 페이지에는 거의 나와 있지 않아요. 세 가지를 물어보세요.

실패하면 환불되나요? eroq에서는 실패한 생성이 자동으로 환불돼요. 시도 횟수가 아니라 성공한 건만 정산하면 돼요.

정책상 거부된 요청도 과금되나요? 차단된 요청은 content_blocked를 반환하고 절대 과금되지 않아요. 규모가 커지면, 거부된 요청에 요금을 매기는 플랫폼은 자기 필터 비용을 고객에게 떠넘기는 셈이에요.

확인은 차감 전인가요, 후인가요? 플랜에 포함되지 않은 모델은 크레딧이 움직이기 전에 403 plan_required를 반환하고, 용량이 확보되지 않은 엔진도 차감 전에 503 model_unavailable을 반환해요. 다른 엔진으로 몰래 대체하지도 않아요. 특정 모델을 요청했는데 쓸 수 없다면, 뜻밖의 렌더러가 아니라 오류를 받게 돼요. 조용한 대체는 이 분야에서 최악의 실패 방식이에요. 결과물은 바뀌는데 로그는 그대로니까요.

4. 과금 단위

주로 두 가지 방식이 쓰여요. 초 단위 종량 과금, 그리고 정해진 기준 길이마다 클립당 고정 크레딧. 고정 기준은 예산을 짜기도, 재무팀에 설명하기도 쉬워요. 초 단위는 애매한 길이에서 더 공정하고요. 어느 쪽도 틀리지 않지만, 고객에게 가격을 약속하기 전에 어떤 방식인지는 알고 있어야 해요.

eroq는 엔진별 기준 길이에 따라 크레딧을 과금해요. Seedance 1.0 Lite 5초에 120 크레딧, Motion One은 60, Kling 2.5 Turbo는 170, 8초 고정인 Veo 3 Fast는 216, 이런 식으로 /models의 전체 라인업에 적용돼요. 입문 팩 기준으로 1크레딧은 약 1센트예요. 크레딧은 만료되지 않고, 워크스페이스는 모든 시트와 키가 함께 쓰는 지갑 하나를 가져요. 덕분에 결제 관계가 여러 개로 흩어지지 않고, 고객별 정산은 여러분 쪽에서 처리하면 돼요. 생성 기능을 재판매한다면 종량 비용을 고객에게 넘기는 방법을 AI API의 크레딧 가격 책정에 정리해 뒀어요.

5. 플랜에 따라 늘어나는 레이트 리밋

eroq의 키별 한도는 분당 요청 수 기준으로 채팅 60, 이미지 20, 동영상과 음성 합성 6에서 시작하고, 여기에 플랜별 배수가 곱해져요. Creator ×2, Studio ×4, Team ×6, Agency ×8. 키 개수도 플랜에 따라 늘어나요. Hobby 10개, Creator 20개, Studio 50개, Team 100개, Agency 200개. 시트만은 예외예요. 개인 플랜은 모두 2개에서 멈추고, 실제 팀이라면 Team(시트 25개)이나 Agency(50개)로 옮겨야 해요.

실무 팁은 환경마다 키 하나, 고객에게 노출되는 서비스마다 키 하나씩 발급하는 거예요. 그래야 스테이징에서 폭주한 루프가 스테이징만 막아요. 어느 업체든 한도가 키별인지 계정 전체인지 확인하세요. 두 방식은 문제가 생겼을 때 피해 범위가 크게 달라요.

6. 라인업을 하드코딩하지 않는 디스커버리

라인업은 바뀌어요. 앱에 엔진 ID와 가격을 하드코딩하면 철 지난 메뉴를 배포하게 돼요.

GET /v1/engines는 각 엔진의 플랜 제한, 가용 여부, 기능(시드, 엔드 프레임, 네거티브 프롬프트, 오디오 지원 여부)을 반환하고, GET /v1/models는 가격이 포함된 전체 모델 목록을 반환해요. 이 두 응답으로 UI를 만들면 새 엔진이 알아서 나타나요. 스펙은 /openapi.json에서 기계가 읽을 수 있는 형태로 제공되고, 코딩 에이전트용 /llms.txt도 있어요.

7. 에이전트용 인터페이스: MCP와 CLI

동영상 API를 호출하는 주체가 앱이 아니라 에이전트인 경우가 점점 늘고 있어요. 갖춰 둘 만한 인터페이스는 두 가지예요.

원격 MCP 서버. eroq의 MCP 서버는 Streamable HTTP로 https://eroq.ai/mcp에서 동작하고, 같은 Bearer 키로 인증하며 generate_image, generate_video, get_video_status, generate_speech, enhance_prompt, list_models, list_voices, list_characters, get_account를 제공해요. ChatGPT에는 커스텀 커넥터로, 웹과 데스크톱의 Claude, Cursor, Codex CLI에도 연결돼요. 헤더를 보낼 수 없는 클라이언트를 위해 /mcp/<key> 형식도 있는데, 이때는 URL 자체가 비밀 값이니 그렇게 다뤄야 해요. 클라이언트별 설정은 /docs/mcp에서 확인하세요.

claude mcp add --transport http eroq https://eroq.ai/mcp \
  --header "Authorization: Bearer $EROQ_API_KEY"

CLI. eroq 패키지는 의존성 없이 Node 18+에서 돌아가요. eroq login, eroq image "…", eroq video "…" -s 8 --aspect 9:16, eroq speech "…" -v aria. eroq mcp는 미디어를 파일로 저장하는 로컬 stdio MCP 서버를 띄우는데, 코딩 에이전트가 실제로 원하는 게 바로 이런 형태예요.

기본을 넘어섰다면 두 가지 더

배치 구조. 단발성 렌더가 아니라 시퀀스를 렌더한다면, 시퀀스를 그대로 모델링하는 리소스가 있는지 찾아보세요. eroq의 films 리소스는 스토리보드를 저장하고, POST /v1/films/{id}/render는 모든 씬을 촬영하면서 씬 단위로 과금하고 지갑이 바닥나면 깔끔하게 멈춰요. 자세한 내용은 /docs/films를 참고하세요.

결과물 호스팅. 렌더 URL은 영구 저장소가 아니에요. 성공 웹훅을 받을 때 자체 버킷으로 복사하거나, /v1/storage/objects의 eroq Store(10 MB당 2 크레딧)를 써서 기록 시스템을 하나로 유지하세요.

체크리스트

1. 복구용 목록 엔드포인트를 갖춘 비동기 작업.
2. 바이트가 아닌 URL을 담은 서명된 웹훅.
3. 실패 시 자동 환불, 정책 거부는 과금 없음.
4. 차감 전 플랜 확인, 다른 엔진으로 몰래 대체하지 않기.
5. 고객에게 견적을 낼 수 있는 과금 단위.
6. 플랜에 따라 늘어나는 키별 레이트 리밋.
7. 모델, 가격, 기능을 런타임에 조회하는 디스커버리.

이 목록을 어느 업체에든, 저희까지 포함해서 대입해 보세요. 위 내용은 모두 /docs에 문서화되어 있고, 가격은 /pricing에서 볼 수 있어요.

자주 묻는 질문

eroq 동영상 API는 동기식인가요, 비동기식인가요?

비동기식이에요. POST /v1/videos/generations가 작업 ID를 반환하면, 작업을 폴링하거나 서명된 video.generation.succeeded 웹훅을 받으면 돼요. 목록 엔드포인트가 워크스페이스의 최근 작업을 돌려주기 때문에 재시작해도 렌더를 잃지 않아요.

동영상 렌더가 실패해도 요금이 나가나요?

아니요. 실패한 생성은 자동으로 환불되고, 콘텐츠 정책으로 차단된 요청은 과금 없이 content_blocked를 반환해요. 플랜 제한과 사용할 수 없는 엔진은 크레딧이 움직이기 전에 확인해요.

코드 대신 에이전트에서 동영상 API를 호출할 수 있나요?

네. https://eroq.ai/mcp의 원격 MCP 서버가 생성, 상태 확인, 계정 도구를 ChatGPT, Claude, Cursor, Codex에 제공하고, eroq CLI에는 렌더 결과를 파일로 저장하는 로컬 stdio MCP 서버가 들어 있어요.

API 키를 발급받고 첫 작업을 보내 보세요. /signup