Video API

OpenRouter Video Generation 표준과 호환되는 통합 비디오 생성 API입니다. 하나의 스키마로 text-to-video, image-to-video, first/last-frame, reference-guided 생성을 모두 처리합니다. 작업을 비동기로 제출한 뒤, 완료되면 폴링하거나 webhook으로 수신하세요.

기능	상세
Base URL	`https://api.ofox.ai`
프로토콜 스타일	OpenRouter 호환（비동기 제출 → 폴링 / webhook）
생성 모드	암묵적으로 추론됨: 이미지 없음 = text-to-video · `frame_images` = image / first-last frame · `input_references` = reference-guided
결과 전달	`GET` 폴링（속도 제한 보호）또는 `callback_url` webhook（HMAC 서명, 재시도）
비디오 저장	업스트림 원본 URL（임시）+ 선택적 CDN 미러（영구 signed URL）

인증

모든 요청은 HTTP Header에 ofox API key（형식 sk-xxx…）를 포함합니다:


Authorization: Bearer $OFOX_API_KEY

callback_url은 HTTPS여야 합니다. Webhook 대상은 SSRF 검증을 거치며, private, loopback, cloud-metadata 주소는 거부됩니다. HTTPS가 아니거나 내부 주소인 경우 생성 시점에 400 invalid_callback_url로 실패합니다.

빠른 시작

1. 작업 제출

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

호출은 polling URL과 함께 즉시 202를 반환합니다:


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

2. 완료될 때까지 폴링

Terminal


curl https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718 \
  -H "Authorization: Bearer $OFOX_API_KEY"

status가 terminal state인 completed, failed, cancelled, expired 중 하나가 될 때까지 요청하세요. 초당 한 번보다 빠르게 폴링하지 마세요. 폴링 대신 webhook을 받으려면 작업 생성 시 callback_url을 전달하세요. 비디오 상태 조회와 Webhooks를 참조하세요.

엔드포인트

메서드	엔드포인트	설명
`POST`	`/v1/videos`	비디오 작업 생성
`GET`	`/v1/videos/{id}`	작업 상태와 결과 조회
`DELETE`	`/v1/videos/{id}`	작업 취소

초당 요금

비디오 모델은 토큰이 아니라 시간 기준으로 과금됩니다. 해상도, 입력 유형, 오디오 옵션에 맞는 pricing.video_pricing.tiers 항목이 초당 USD 요금을 결정합니다. pricing.output_video_per_second는 모델의 최저 시작 요금일 뿐입니다. 예상 비용은 tier 요금 × 요청 시간으로 계산하고, 완료 후에는 응답의 usage.video_seconds와 usage.video_cost를 최종 과금 시간과 실제 비용으로 사용하세요. 비디오 변환 작업에서는 입력 비디오 시간이 과금 초에 포함될 수 있습니다.

다음 단계

비디오 생성 비디오 상태 조회 비디오 취소 Webhooks 에러 코드