OmniVideo API로 동영상·이미지 생성 자동화하기: REST API 연동 구현 가이드

OmniVideo는 텍스트나 이미지로부터 AI를 통해 동영상·이미지를 생성할 수 있는 서비스입니다. Web UI뿐만 아니라 REST API가 공개되어 있어, 외부 시스템이나 배치 처리 (Batch Processing)로부터 생성을 통합할 수 있습니다. 본 기사에서는 API 인증부터 태스크 생성, 결과 취득 (Polling)까지의 일련의 구현을 cURL과 코드 예제를 통해 해설합니다.

API의 전체 모습

OmniVideo의 API는 "태스크를 생성하고, 상태를 폴링 (Polling)으로 취득하는" 비동기 (Asynchronous) 방식입니다. 동영상·이미지 생성에는 시간이 걸리기 때문에, 요청 시 즉시 task_id가 반환되며, 생성 완료 후에 결과물의 URL을 취득합니다.

• 베이스 URL (Base URL):
  https://omnivideo.net/api/v1

• 인증 방식 (Authentication):
  Bearer 토큰 (HTTP 헤더)

• 응답 형식 (Response Format):
  JSON

1. API 키 취득

API를 호출하려면 API 키가 필요합니다. OmniVideo에 로그인하여 계정 페이지에서 키를 발행해 주세요. 발행되는 키는 sk-로 시작하는 문자열입니다.

요청 시에는 Authorization 헤더에 Bearer 토큰으로 부여합니다.

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. 이용 가능한 모델

model_id	종별	출력
omni-flash	텍스트/이미지 → 동영상	video_url
omni-pro	텍스트/이미지 → 동영상	video_url
seedance-2	텍스트/이미지 → 동영상	video_url
gpt-image-2	텍스트/이미지 → 이미지	image_url
nano-banana-2	텍스트/이미지 → 이미지	image_url

model_id를 전환하는 것만으로, 동일한 인터페이스에서 동영상 생성과 이미지 생성을 구분하여 호출할 수 있습니다.

3. 태스크 생성

POST /api/v1/tasks/create에 모델과 프롬프트 (Prompt)를 지정하여 송신합니다.

curl -X POST https://omnivideo.net/api/v1/tasks/create \-
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \-
-H "Content-Type: application/json" \-
...

요청 바디 (Request Body)의 주요 필드는 다음과 같습니다.

• model_id: 사용할 모델 ID (필수)
• prompt: 생성 내용을 나타내는 텍스트 (필수)
• image_urls: 입력 이미지를 사용하는 경우의 URL 배열 (image-to-video / image-to-image 용. 사용하지 않으면 빈 배열)
• aspect_ratio: 종횡비 (예: 16:9)

성공 시의 응답:

{
"code": 200,
"msg": "提交成功，等待生成",
...

task_id가 반환되면, 이를 사용하여 결과를 폴링 (Polling)합니다. 크레딧 (Credit)은 송신 시점에 소비됩니다 (credits 필드 참조).

4. 태스크 조회와 상태

GET /api/v1/tasks/{task_id}로 진행 상황과 결과를 취득합니다.

curl https://omnivideo.net/api/v1/tasks/abcdef123456 \-
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

응답 예시:

{
"code": 200,
"msg": "ok",
...

task_status의 값:

값	상태
1	queued (대기 중)
...	task_status가 3이 되면 image_url 또는 video_url로부터 결과물을 취득할 수 있습니다. 4 (실패)인 경우에는 소비한 크레딧이 자동으로 반환됩니다.

5. 폴링 (Polling) 구현 예시 (Python)

task_status가 3 또는 4

될 때까지 일정 간격으로 조회하는 최소한의 구현입니다.

import time
import requests
BASE = "https://omnivideo.net/api/v1"
...

Node.js (fetch)에서도 마찬가지로, tasks/create에서 받은 task_id를 tasks/{task_id}에 전달하여 폴링 (Polling)하기만 하면 됩니다.

6. 에러 핸들링 (Error Handling)

• code: 200 … 성공
• code: 0 … 비즈니스 에러 (msg 내용 확인 필요)
• HTTP 401 … API 키가 무효하거나 지정되지 않음

code는 HTTP 상태 코드 (Status Code)와 별개로 응답 본문 (Response Body) 내에서 반환되므로, HTTP 상태 코드와 함께 두 가지를 모두 확인하는 것이 안전합니다. 실패한 태스크의 크레딧은 자동으로 반환되므로, 재시도 (Retry) 로직을 구현하기에도 용이한 설계입니다.

요약

OmniVideo의 API는 "생성 → 폴링 (Polling) → 취득"이라는 단순한 비동기 (Asynchronous) 모델을 따르며, model_id를 변경하는 것만으로 여러 동영상 및 이미지 모델을 동일한 흐름에서 다룰 수 있습니다. 실제로 테스트해 보려면 Omni Video에 로그인하여 계정 페이지에서 API 키를 발급받은 후, 본 기사의 코드 내에 있는 sk-...를 교체하여 사용하세요.

Discussion