메인 콘텐츠로 건너뛰기
POST
오른쪽의 대화형 Playground에서 호출을 실시간으로 테스트할 수 있습니다. Authorization에 API 키(형식 Bearer sk-xxx)를 입력하고 prompt, seconds, size를 작성한 다음 전송합니다. 응답은 작업 id이며, 아래 쿼리 엔드포인트를 사용하여 동영상을 가져옵니다.
하나의 엔드포인트, 네 가지 모드: prompt만 사용하면 텍스트-동영상 변환이고, input_reference에 이미지 하나를 넣으면 첫 프레임 동영상이 생성됩니다. input_reference에 JSON 래퍼를 넣으면 첫 프레임과 마지막 프레임 또는 참조 미디어 동영상이 생성되며, 이 래퍼에서 768p, 1:1 또는 품질 등급도 선택할 수 있습니다. 전체 내용은 Oxygen 개요를 참조하십시오.
⚠️ 가장 흔한 실수 네 가지
  1. 항상 size를 전달하십시오: 이를 전달하지 않으면 게이트웨이는 기본값으로 720x1280를 사용하므로 세로 방향 출력이 생성됩니다
  2. 고급 매개변수는 input_reference 래퍼에 넣으십시오: 최상위 수준에서는 model, prompt, seconds, size, input_reference만 적용됩니다. 해당 위치에 배치한 last_image, reference_images, resolution, aspect_ratio는 오류 없이 조용히 무시됩니다
  3. input_reference은 문자열이어야 합니다: 먼저 json.dumps / JSON.stringify로 래퍼를 직렬화하십시오. 객체나 배열을 전달하면 거부됩니다
  4. 길이는 최상위 seconds로만 설정하십시오(4–15): 래퍼 내부의 duration은 400 오류를 반환합니다

코드 예제

Python (requests · 제출 + 폴링 + 다운로드)

Python (첫 프레임 동영상 · 요청 본문)

Python (첫 프레임 및 마지막 프레임 / 참조 미디어 · JSON 엔벌로프)

cURL

첫 프레임 및 마지막 프레임(input_reference의 값은 이스케이프된 JSON 문자열입니다):

Node.js (네이티브 fetch)

ID가 있습니까? 결과를 가져오는 cURL 하나

status이 completed이면 video_url은 MP4 주소이며 직접 다운로드할 수 있습니다:

매개변수 참조

최상위 필드(이 다섯 개만 적용됨)

input_reference 엔벌로프 키

엔벌로프에는 duration을 포함할 수 없으며(최상위 seconds을 사용해야 함), 표에 없는 키도 포함할 수 없습니다. 또한 첫/마지막 프레임(images / last_image)은 reference_*와 함께 사용할 수 없습니다. 이러한 경우 모두 400(param: input_reference)을 반환하며 과금되지 않습니다.

해상도 및 출력 크기(측정값)

이미지-동영상 변환은 첫 프레임의 가로세로 비율을 따릅니다. 예를 들어 정사각형 첫 프레임은 480p에서 480×480으로 생성됩니다.

응답 형식

작업 생성

작업 조회(성공)

작업 조회(실패)

제출 오류(400)

⚠️ 응답 참고 사항
  • 상태는 queued → in_progress → completed / failed 순서로 변경됩니다.
  • 동영상은 **video_url**에 있으며 인증 헤더 없이 다운로드할 수 있습니다. expires_at(약 24시간) 후 만료되므로 즉시 저장하시기 바랍니다.
  • completed 직후에는 /v1/videos/{id}/content에 몇 초가 더 필요할 수 있습니다(처음에는 400을 반환함). video_url을 우선 사용하시기 바랍니다.
  • usage.unit_price_usd은 해상도별 기준 가격이며, 실제 과금은 청구서에 따릅니다: 초당 고정 $0.02입니다.
  • 제출 오류의 세부 정보는 message 내부의 JSON 문자열로 반환되며 다시 파싱해야 합니다.
과금: 작업이 승인되면 seconds × \$0.02이 과금됩니다. 해상도와 참조 미디어는 가격에 영향을 주지 않으며, 실패한 작업은 자동으로 전액 환불됩니다. 400을 반환하는 제출에는 과금되지 않으며, 조회와 다운로드는 무료입니다. 개요의 가격 정보를 참조하시기 바랍니다.

인증

Authorization
string
header
필수

API key from the APIYI console

본문

application/json
model
enum<string>
기본값:oxygen-1.0
필수

Always oxygen-1.0

사용 가능한 옵션:
oxygen-1.0
prompt
string
필수

Video description

예시:

"A paper boat drifting on a calm pond, soft morning light"

seconds
enum<string>
기본값:4
필수

Output length in seconds, integer 4–15, as a string or number. Used for billing; the clip usually runs slightly longer

사용 가능한 옵션:
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15
size
enum<string>
기본값:1280x720

Sets the resolution and orientation. Pass it every time; it defaults to 720x1280 (portrait) when omitted. 1280x720 = 480p landscape, 720x1280 = 480p portrait, 1792x1024 = 768p landscape, 1024x1792 = 768p portrait. For 1:1, use aspect_ratio in the input_reference envelope.

사용 가능한 옵션:
1280x720,
720x1280,
1792x1024,
1024x1792
input_reference
string

Two forms:

  • Image URL or data URI → first-frame video; aspect ratio follows the first frame
  • JSON string starting with { (envelope) → allowed keys: images (first frame, max 1), last_image (last frame), reference_images (up to 9), reference_videos (up to 3, https only), reference_audios (up to 3, https only), resolution (480p / 768p, wins over size), aspect_ratio (16:9 / 9:16 / 1:1, ignored for image-to-video), quality (high default / normal), prompt_enhance (refine default / format / none), prompt

Must be a string, so serialize the envelope first. No duration and no unknown keys in the envelope; first/last frames cannot be mixed with reference media.

예시:

"https://your-cdn.example.com/first.png"

응답

Task accepted

id
string

Task id, used with GET /v1/videos/{id}

object
enum<string>
사용 가능한 옵션:
video
model
string
status
enum<string>
사용 가능한 옵션:
queued,
in_progress,
completed,
failed
progress
integer

0–100

seconds
string
size
string
created_at
integer
completed_at
integer
expires_at
integer

When video_url expires (Unix seconds), about 24 hours after completion

video_url
string

Output MP4 URL, downloadable without an auth header; store it promptly

usage
object

Reference billing info; actual billing is a flat $0.02 per second, see your bill

error
object