curl --request POST \
--url https://api.apiyi.com/v1/videos \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "oxygen-1.0",
"prompt": "A paper boat drifting on a calm pond, soft morning light",
"seconds": "4"
}
'{
"id": "task_PSOFP1GQLtN6kGLXv9DpHMkMGBka70Ga",
"object": "video",
"model": "oxygen-1.0",
"status": "queued",
"progress": 0,
"seconds": "4",
"size": "1280x720",
"created_at": 1790853159
}Oxygen 동영상 생성 (AZ8)
Oxygen 동영상 생성 API 레퍼런스
Oxygen(oxygen-1.0) 동영상 생성 API 레퍼런스 및 라이브 플레이그라운드: OpenAI Videos 호환, POST /v1/videos로 제출하고 GET /v1/videos/로 조회하며, 엔벌로프를 통한 첫 프레임/마지막 프레임 및 참조 미디어를 지원하고 초당 과금됩니다.
POST
/
videos
curl --request POST \
--url https://api.apiyi.com/v1/videos \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "oxygen-1.0",
"prompt": "A paper boat drifting on a calm pond, soft morning light",
"seconds": "4"
}
'{
"id": "task_PSOFP1GQLtN6kGLXv9DpHMkMGBka70Ga",
"object": "video",
"model": "oxygen-1.0",
"status": "queued",
"progress": 0,
"seconds": "4",
"size": "1280x720",
"created_at": 1790853159
}오른쪽의 대화형 Playground에서 호출을 실시간으로 테스트할 수 있습니다. Authorization에 API 키(형식
Bearer sk-xxx)를 입력하고 prompt, seconds, size를 작성한 다음 전송합니다. 응답은 작업 id이며, 아래 쿼리 엔드포인트를 사용하여 동영상을 가져옵니다.하나의 엔드포인트, 네 가지 모드:
prompt만 사용하면 텍스트-동영상 변환이고, input_reference에 이미지 하나를 넣으면 첫 프레임 동영상이 생성됩니다. input_reference에 JSON 래퍼를 넣으면 첫 프레임과 마지막 프레임 또는 참조 미디어 동영상이 생성되며, 이 래퍼에서 768p, 1:1 또는 품질 등급도 선택할 수 있습니다. 전체 내용은 Oxygen 개요를 참조하십시오.⚠️ 가장 흔한 실수 네 가지
- 항상
size를 전달하십시오: 이를 전달하지 않으면 게이트웨이는 기본값으로720x1280를 사용하므로 세로 방향 출력이 생성됩니다 - 고급 매개변수는
input_reference래퍼에 넣으십시오: 최상위 수준에서는model,prompt,seconds,size,input_reference만 적용됩니다. 해당 위치에 배치한last_image,reference_images,resolution,aspect_ratio는 오류 없이 조용히 무시됩니다 input_reference은 문자열이어야 합니다: 먼저json.dumps/JSON.stringify로 래퍼를 직렬화하십시오. 객체나 배열을 전달하면 거부됩니다- 길이는 최상위
seconds로만 설정하십시오(4–15): 래퍼 내부의duration은 400 오류를 반환합니다
코드 예제
Python (requests · 제출 + 폴링 + 다운로드)
import os
import time
import requests
API_KEY = os.environ["APIYI_API_KEY"]
BASE = "https://api.apiyi.com/v1/videos"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
# Step 1: submit the task
payload = {
"model": "oxygen-1.0",
"prompt": "A paper boat drifting on a calm pond, soft morning light",
"seconds": "4", # 4–15, billed per second
"size": "1280x720", # always pass it: 1280x720 = 480p landscape
}
r = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
r.raise_for_status()
video_id = r.json()["id"]
print("id:", video_id)
# Step 2: poll (usually 1–3 minutes, wait up to 15 minutes)
deadline = time.time() + 900
while time.time() < deadline:
job = requests.get(f"{BASE}/{video_id}", headers=HEADERS, timeout=30).json()
print(job["status"], job.get("progress"))
if job["status"] == "completed":
video_url = job["video_url"]
break
if job["status"] == "failed":
# Failed tasks are refunded automatically; error has the reason
raise RuntimeError(job.get("error"))
time.sleep(5)
else:
raise TimeoutError(video_id)
# Step 3: download video_url directly (no auth header; valid ~24 hours, store it promptly)
with requests.get(video_url, stream=True, timeout=300) as v, open("output.mp4", "wb") as f:
v.raise_for_status()
for chunk in v.iter_content(1 << 16):
f.write(chunk)
print("Saved: output.mp4")
Python (첫 프레임 동영상 · 요청 본문)
payload = {
"model": "oxygen-1.0",
"prompt": "The glass sphere rolls slowly across the table",
"seconds": "4",
"size": "1280x720", # sets the resolution (480p); aspect ratio follows the first frame
"input_reference": "https://your-cdn.example.com/first.png", # a data:image/...;base64,... URI also works
}
Python (첫 프레임 및 마지막 프레임 / 참조 미디어 · JSON 엔벌로프)
import json
# First and last frame: the envelope is a JSON string, json.dumps it into input_reference
envelope = {
"images": ["https://your-cdn.example.com/first.png"], # first frame (max 1)
"last_image": "https://your-cdn.example.com/last.png", # last frame
}
payload = {
"model": "oxygen-1.0",
"prompt": "The glass sphere slowly dissolves into a deep blue abstract wave",
"seconds": "5",
"size": "1280x720",
"input_reference": json.dumps(envelope),
}
# Reference media + portrait + 768p (reference media cannot be mixed with first/last frames)
envelope = {
"reference_images": ["https://your-cdn.example.com/character.png"], # up to 9
"reference_videos": ["https://your-cdn.example.com/motion.mp4"], # up to 3, https only
"aspect_ratio": "9:16",
"resolution": "768p", # resolution in the envelope wins over size (480p / 768p only)
}
payload = {
"model": "oxygen-1.0",
"prompt": "The character from the reference image dances following the reference video",
"seconds": "8",
"size": "720x1280",
"input_reference": json.dumps(envelope),
}
cURL
curl -X POST "https://api.apiyi.com/v1/videos" \
-H "Authorization: Bearer $APIYI_API_KEY" \
-H "Content-Type: application/json" \
--max-time 60 \
-d '{
"model": "oxygen-1.0",
"prompt": "A lighthouse at dusk, waves crashing on the rocks",
"seconds": "4",
"size": "1792x1024"
}'
input_reference의 값은 이스케이프된 JSON 문자열입니다):
curl -X POST "https://api.apiyi.com/v1/videos" \
-H "Authorization: Bearer $APIYI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "oxygen-1.0",
"prompt": "The glass sphere slowly dissolves into a deep blue abstract wave",
"seconds": "5",
"size": "1280x720",
"input_reference": "{\"images\":[\"https://your-cdn.example.com/first.png\"],\"last_image\":\"https://your-cdn.example.com/last.png\"}"
}'
Node.js (네이티브 fetch)
const API_KEY = process.env.APIYI_API_KEY;
const BASE = 'https://api.apiyi.com/v1/videos';
const headers = { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' };
const submit = await fetch(BASE, {
method: 'POST',
headers,
body: JSON.stringify({
model: 'oxygen-1.0',
prompt: 'Aurora drifting over snowy mountains, time-lapse feel',
seconds: '8',
size: '1280x720',
// Advanced parameters: JSON.stringify the envelope into a string first
input_reference: JSON.stringify({ resolution: '768p' }),
}),
});
if (!submit.ok) throw new Error(`submit ${submit.status}: ${await submit.text()}`);
const { id } = await submit.json();
let job;
for (;;) {
await new Promise(r => setTimeout(r, 5000));
job = await (await fetch(`${BASE}/${id}`, { headers })).json();
if (job.status === 'completed' || job.status === 'failed') break;
}
if (job.status === 'failed') throw new Error(JSON.stringify(job.error));
console.log('video:', job.video_url);
ID가 있습니까? 결과를 가져오는 cURL 하나
curl "https://api.apiyi.com/v1/videos/task_xxxxxxxxxxxxxxxx" \
-H "Authorization: Bearer $APIYI_API_KEY"
status이 completed이면 video_url은 MP4 주소이며 직접 다운로드할 수 있습니다:
curl -L -o output.mp4 "<value of video_url>"
매개변수 참조
최상위 필드(이 다섯 개만 적용됨)
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
model | string | 예 | 항상 oxygen-1.0입니다 |
prompt | string | 예 | 동영상 설명 |
seconds | string / integer | 예 | 4–15 사이의 정수이며 과금에 사용됩니다 |
size | string | 강력히 권장 | 1280x720 / 720x1280(480p), 1792x1024 / 1024x1792(768p)이며, 생략하면 기본값은 720x1280입니다 |
input_reference | string | 아니요 | 이미지 URL 또는 데이터 URI = 첫 프레임입니다. {으로 시작하는 JSON 문자열은 엔벌로프입니다(아래 참조) |
input_reference 엔벌로프 키
| 키 | 유형 | 설명 |
|---|---|---|
images | string[] | 첫 프레임, 최대 1개(https 또는 이미지 데이터 URI) |
last_image | string | 마지막 프레임(https 또는 이미지 데이터 URI) |
reference_images | string[] | 참조 이미지, 최대 9개 |
reference_videos | string[] | 참조 동영상, 최대 3개, https만 허용 |
reference_audios | string[] | 참조 오디오, 최대 3개, https만 허용 |
resolution | string | 480p / 768p이며 size보다 우선합니다. 320p는 2026-10-14에 폐기되었으며 400을 반환합니다 |
aspect_ratio | string | 16:9 / 9:16 / 1:1이며 size보다 우선합니다. 이미지-동영상 변환에서는 무시됩니다 |
quality | string | 품질 등급: high(기본값) / normal이며 가격에는 영향을 주지 않습니다 |
prompt_enhance | string | 프롬프트 향상: refine(기본값, 다듬고 확장함) / format(서식만 정리함) / none(프롬프트를 작성된 그대로 사용함)이며 가격에는 영향을 주지 않습니다 |
prompt | string | 지정된 경우 최상위 prompt을 재정의합니다 |
엔벌로프에는
duration을 포함할 수 없으며(최상위 seconds을 사용해야 함), 표에 없는 키도 포함할 수 없습니다. 또한 첫/마지막 프레임(images / last_image)은 reference_*와 함께 사용할 수 없습니다. 이러한 경우 모두 400(param: input_reference)을 반환하며 과금되지 않습니다.해상도 및 출력 크기(측정값)
| 해상도 | 가로 방향 16:9 | 세로 방향 9:16 | 정사각형 1:1 |
|---|---|---|---|
| 480p | 864×480 | 480×864 | 480×480 |
| 768p | 1376×768 | 768×1376 | 768×768 |
응답 형식
작업 생성
{
"id": "task_PSOFP1GQLtN6kGLXv9DpHMkMGBka70Ga",
"object": "video",
"model": "oxygen-1.0",
"status": "queued",
"progress": 0,
"seconds": "4",
"size": "1280x720",
"created_at": 1790853159
}
작업 조회(성공)
{
"id": "task_R0Sb8B4YqmNxVSkQZSphUZ8GwEebRMRu",
"object": "video",
"model": "oxygen-1.0",
"status": "completed",
"progress": 100,
"seconds": "5",
"created_at": 1790902499,
"completed_at": 1790902566,
"expires_at": 1790988966,
"usage": {
"billing_unit": "second",
"billed_seconds": 5,
"resolution": "480p",
"unit_price_usd": 0.02
},
"video_url": "https://your-video-host.example.com/task_R0Sb8B4Y..._0.mp4"
}
작업 조회(실패)
{
"id": "task_xqNrojcHWebOegX70EZzqpM3EhdXMnOo",
"object": "video",
"model": "oxygen-1.0",
"status": "failed",
"progress": 100,
"error": {
"code": "upstream_timeout",
"message": "upstream did not finish the video within the deadline"
}
}
제출 오류(400)
{
"message": "{\"error\":{\"code\":\"invalid_params\",\"message\":\"input_reference: duration is not used here; set the length with the top-level seconds field\",\"param\":\"input_reference\"}}",
"type": "task_error",
"code": "fail_to_fetch_task"
}
⚠️ 응답 참고 사항
- 상태는
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을 반환하는 제출에는 과금되지 않으며, 조회와 다운로드는 무료입니다. 개요의 가격 정보를 참조하시기 바랍니다.본문
application/json
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 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(highdefault /normal),prompt_enhance(refinedefault /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
이 페이지가 도움이 되었나요?