비디오 상태 조회


GET https://api.ofox.io/v1/videos/{id}

작업의 상태와 결과를 조회합니다. 작업 생성 후 status가 terminal state인 completed, failed, cancelled, expired 중 하나가 될 때까지 이 엔드포인트를 폴링하세요.

Terminal


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

속도 제한

이 엔드포인트는 API key별로 속도 제한이 적용됩니다（기본 5 req/s, burst 20）. 제한을 초과한 요청은 Retry-After: 1 header와 함께 429 rate_limited를 반환합니다. 생성（POST）과 취소（DELETE）에는 이 제한이 적용되지 않습니다.

초당 한 번보다 빠르게 폴링하지 마세요. 폴링 대신 webhook을 받으려면 작업 생성 시 callback_url을 전달하세요.

응답

완료


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "completed",
  "model": "bytedance/seedance-2.5",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.io/videos/vgen_xxx.mp4?sig=..."],
  "usage": {
    "video_seconds": 5,
    "video_cost": "0.4000000000"
  },
  "created_at": 1776211362,
  "updated_at": 1776211400
}

Timeout은 status: "failed"와 expired로 설정된 error.code로 보고됩니다. 전체 error code 목록은 에러 코드를 참조하세요.

Video object

필드	타입	설명
`id`	string	고유 작업 식별자（UUID）
`status`	enum	State machine 참조
`model`	string	Model slug
`prompt`	string	원본 prompt
`unsigned_urls`	string[]	`completed`일 때 존재. 업스트림 원본 비디오 URL（임시, 24h 내 만료될 수 있음）
`mirror_urls`	string[]	`completed`이고 모델 공급자에 CDN mirroring이 활성화되어 있을 때 존재. 영구 signed URL — Video URLs 참조
`error`	object	`failed`일 때 존재: `{code, message}`
`usage`	object	`completed`일 때 존재: `{video_seconds, video_cost}`. `video_seconds`는 과금 초（v2v 입력 초 포함）이며, `video_cost`는 platform tier price 기준 실제 청구액으로, 정밀도 손실을 피하기 위한 고정 소수점 10자리 문자열입니다
`created_at` / `updated_at`	integer	Unix seconds

State machine

OpenRouter naming을 기반으로 하고 cancelled / expired를 확장한 7개 상태입니다.

Status	Terminal	설명
`pending`	—	수락됨, 아직 업스트림에 제출되지 않음
`queued`	—	업스트림에 제출됨, queue에서 대기 중
`in_progress`	—	업스트림에서 생성 중
`completed`	✓	성공, 비디오 URL 사용 가능
`failed`	✓	실패（timeout 포함, `error.code=expired`）
`cancelled`	✓	취소됨
`expired`	✓	만료됨

Transitions: pending → queued → in_progress → completed가 성공 경로입니다. 모든 non-terminal state는 failed, cancelled, expired로 이동할 수 있습니다.

Video URLs

성공한 작업은 모델 공급자의 CDN mirroring 활성화 여부에 따라 두 종류의 URL 세트를 반환할 수 있습니다.

필드	출처	특성
`unsigned_urls`	업스트림 공급자의 원본 주소	임시 — 항상 존재 · 24h 내 만료될 수 있음 · unsigned
`mirror_urls`	ofox CDN mirror	영구 — CDN-enabled providers에만 해당 · 요청마다 signed · TTL 있음

mirror_urls（영구적이고 안정적）사용을 권장합니다. 모델이 unsigned_urls만 반환하는 경우, 업스트림 임시 주소가 만료되기 전에 파일을 즉시 다운로드하거나 다시 호스팅하세요.