본문으로 건너뛰기
원포트 AI

영상 — /v1/videos

글(과 그림 한 장)로 짧은 영상을 만듭니다. 만들고, 끝났는지 보고, 받습니다.

AI 에게 넘기기ChatGPT 에서 열기 (새 창)Claude 에서 열기 (새 창)원문 열기

영상은 몇십 초에서 몇 분 걸려서 한 번의 호출로 기다리지 않아요. 만들기를 부르면 바로 작업 id 가 오고, 그 id 로 끝났는지 보다가, 끝나면 mp4 를 받으세요. OpenAI /v1/videos 모양 그대로라 공식 SDK 의 videos.create · retrieve · download_content 가 그대로 붙어요.

만들기 → 끝났는지 보기 → 받기
# 1) 만들기 — 몇 초 안에 id 가 와요
curl https://oneport.kr/v1/videos \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"칠판 앞에서 분필로 하트를 그리는 손, 따뜻한 햇살","seconds":"4","size":"1280x720"}'

# 2) 끝났는지 보기 — status 가 completed 가 될 때까지 5초마다
curl https://oneport.kr/v1/videos/video_… -H "Authorization: Bearer $ONEPORT_API_KEY"

# 3) 받기 — 끝난 영상이면 302 로, 10분 동안 유효한 저장소 주소로 넘겨드려요(-L 로 따라가 주세요 · 그 주소는 키 없이 열려요)
#    아직 만드는 중이면 409, 실패했거나 지운 · 보관 기간이 지난 영상이면 404, 주소를 잠깐 못 만들면 503 이에요(잠시 뒤 다시)
#    302 의 location 은 https:// 로 시작하는 완전한 주소예요 — Python requests 는 allow_redirects=False 로 받아 그 주소를 키 없이 GET 하면 돼요
#    Node fetch 는 { redirect: "manual" } 로 302 의 location 머리글을 읽어, 그 주소를 키 없이 다시 받으면 돼요
curl -L https://oneport.kr/v1/videos/video_…/content -H "Authorization: Bearer $ONEPORT_API_KEY" -o clip.mp4
그림 한 장으로 시작하기 (multipart)
curl https://oneport.kr/v1/videos \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F model=grok-imagine-video \
  -F prompt="이 상품 사진에서 천천히 다가가는 장면" \
  -F seconds=8 \
  -F size=720x1280 \
  -F input_reference=@product.jpg

# 그림 파일은 input_reference 칸에 담아요. 글자 칸(seconds 등)은 글자로 보내도 돼요.
# Idempotency-Key 는 머리글이라 JSON · multipart 둘 다 받아요.
공식 SDK (openai-python)
import os
from openai import OpenAI
client = OpenAI(base_url="https://oneport.kr/v1", api_key=os.environ["ONEPORT_API_KEY"])
video = client.videos.create_and_poll(model="grok-imagine-video", prompt="종이배가 잔잔한 호수 위를 떠가는 모습", seconds="4")
if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("clip.mp4")

요청 파라미터#

만들기 — POST /v1/videos (JSON 또는 multipart/form-data)

파라미터받는 값저희가 하는 일
model필수영상 모델 id글·그림 모델을 넣으시면 400 으로 맞는 문을 알려드려요.
prompt필수문자열(32,000자까지)손대지 않고 벤더에 닿아요. runway-gen4.5 는 영어로 적은 지시만 받아요(한글이 있으면 400) · 1,000자까지예요. Gemini Omni(아직 판매 전이에요 — GET /v1/models 에 없으면 부를 수 없어요)는 한국어 지시도 받지만 영어를 가장 잘 따라요 — 빼고 싶은 것도 prompt 안에 「~는 넣지 마」로 적어요. 사람이 담긴 그림을 받을지는 각 AI 회사의 안전 기준이 정해요(저희가 따로 거르지 않아요). AI 회사가 안전 기준 · 저작권 · 실존 인물 같은 내용으로 거절하면 접수 때든 만드는 중이든 status 가 failed 이고 error.code 가 moderation_blocked 예요 — 같은 내용으로 다시 보내지 말고 글이나 그림을 고쳐서 보내세요. 접수 때 막힌 건 요금이 안 붙고, 만드는 도중 막히면 AI 회사가 매긴 값만큼 사용할 수 있어요(아래 「응답 · 상태」).
seconds"4" 같은 문자열 또는 1~15 정수안 적으시면 4초예요. 모델마다 길이 · 해상도가 달라요(grok-imagine-video 계열은 1~15초 · 화면비 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 3:2 · 2:3 모두 · grok-imagine-video 는 480p · 720p, -1.5 는 1080p 까지, Runway 는 720p · 2~10초 · 소리 없음 · 화면비는 그림이 있으면 16:9 · 9:16 · 1:1 · 4:3 · 3:4, 글만이면 16:9 · 9:16, Seedance 는 4~15초 · 화면비 16:9 · 9:16 · 1:1 · 4:3 · 3:4, Gemini Omni 는 720p · 3~10초 · 16:9 · 9:16 만) — GET /v1/models 의 pricing.video 에서 min_seconds · max_seconds · resolutions · aspect_ratios · supports_audio · input_image 를 보세요(영상 줄마다 와요). 벤더에 이 길이를 **그대로 적어** 보내서, 미리 잡는 금액과 실제로 떼는 금액이 같은 자로 재져요. xAI 이름 duration 으로 보내셔도 같은 뜻으로 읽어요 — 둘 다 오면 seconds 가 이겨요.
size1280x720 · 720x1280 · 720x720 · 854x480 · 480x854 · 480x480 · 1920x1080 · 1080x1920 · 1080x1080 · 1792x1024 · 1024x1792해상도와 화면비로 풀어서 벤더에 넘겨요. openai SDK 타입에 있는 1792x1024 · 1024x1792 는 720p 16:9 · 9:16 으로 만들어요. 모델이 안 만드는 해상도면(예: grok-imagine-video 의 1080p) 400 이에요.
resolution · aspect_ratio480p · 720p · 1080p / 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 3:2 · 2:3size 대신 이 둘로 보내셔도 돼요. 둘 다 오면 size 가 이겨요.
input_reference · image_url그림 파일(multipart, 4MB) 또는 https·data URI그림 한 장에서 시작하는 영상이에요. 두 장 이상이거나 그림·주소를 다른 이름의 칸에 담으면 400이에요(callback_url 처럼 그림이 아닌 칸이라도 모르는 칸에 주소를 담으면 400). 파일 · data URI · https 주소를 grok-imagine-video 계열 · BytePlus Seedance · Runway 모두 받아요(그림 파일(multipart)은 input_reference 칸으로만 png · jpeg · webp 를 받아요 — gif 파일은 400 이에요. gif 는 data URI 나 https 주소로 보내 주세요(Seedance · Runway). 파일엔 형식(image/png · image/jpeg · image/webp)을 붙여 보내 주세요 — curl -F 는 확장자를 보고 알아서 붙이고, Node openai SDK 는 toFile(fs.readFileSync("product.jpg"), "product.jpg", { type: "image/jpeg" }) 로 넣어요. 형식이 빠졌거나 그림 형식이 아니면 저희가 파일 머리로 png · jpeg · webp 를 알아보고, 그 셋이 아니면 400 이에요.) 저희는 그림을 자르거나 늘리지 않고 그대로 넘겨요 — 그림 비율이 size 와 다르면 어떻게 맞출지는 AI 회사가 정하니, 9:16 영상이면 사진도 9:16 으로 잘라 넣으세요. Higgsfield 경유 Seedance(higgsfield-seedance-2.0 · higgsfield-seedance-2.5 — 지금은 판매하지 않아요)는 입력 그림을 받지 않아요. dreamina-seedance-* 는 받아요. Gemini Omni 는 그림 파일이나 data URI(png · jpeg · webp)만 받아요 — https 주소면 400 이에요. 주소는 저희 서버가 열지 않고 그대로 넘겨요. data URI 는 요청 본문 전체가 4.5MB 를 넘으면 안 돼요 — base64 는 원본보다 1/3쯤 커지니 그림은 3MB 아래로 줄여 주세요(jpeg 를 권해요). 넘으면 저희 코드에 닿기 전에 호스팅이 413 을 주고, 몸통이 JSON 이 아닌 글자(FUNCTION_PAYLOAD_TOO_LARGE)라 error.type 이 없어요. 큰 그림은 multipart 의 input_reference(파일 4MB까지)나 https 주소로 보내 주세요.
generate_audiotrue · false기본은 소리 있음이에요. grok-imagine-video 계열은 꺼도 값이 같아요(09-30 실측). runway-gen4.5 는 소리를 만들지 않아요 — 이 칸을 빼면 저희가 false 로 맞추고, true 를 보내면 400 이에요. GET /v1/models 의 pricing.video.supports_audio 가 false 인 모델엔 이 칸을 빼고 보내세요. Gemini Omni 는 소리를 늘 같이 만들어서 false 면 400 이에요 — 소리는 prompt 에 적어 주세요(예: 잔잔한 피아노 배경음). multipart 로 보낼 땐 generate_audio=false 처럼 글자로 보내요("false" · "0" 이면 꺼요).
Idempotency-Key (헤더)문자열네트워크가 끊겨 다시 보낼 때 두 번 만들지 않게 넣어 주세요. 같은 값이면 본문이 달라도 처음 작업이 HTTP 200 으로 와요(409 는 없어요) — 영상마다 새 값(uuid)을 쓰세요. 값의 꼴은 따지지 않고, 앞뒤 공백을 뺀 앞 200자로 같은 값인지 봐요. 다만 다시 보낸 본문도 공통 칸 검사(prompt 빈칸 · 32,000자 · model · seconds 1~15 · size 꼴)는 먼저 거쳐서, 거기서 막히면(400 · 404) 처음 작업 대신 그 거절이 와요. 모델마다 다른 검사(그 모델이 안 만드는 해상도 · 길이 · 화면비 · runway-gen4.5 의 한글)는 값을 본 뒤라, 같은 값이면 그런 본문에도 처음 작업이 200 으로 와요 — 다시 보낼 땐 처음 본문을 그대로 보내세요. 여러 편을 스크립트로 보낼 땐 값을 보내기 전에 파일에 적어 두세요 — 응답을 받기 전에 프로그램이 멈춰도 같은 값으로 다시 보내면 두 편이 생기지 않아요. 글 문과 다른 점은 아래 「응답 · 상태」에 있어요.
그 밖의 칸 (seed · negative_prompt 등)읽지 않아요위 표에 없는 칸은 읽지 않고 AI 회사에도 넘기지 않아요(그림이나 주소가 담겼으면 400 — 위 input_reference 줄). 넣고 싶은 것 · 빼고 싶은 것은 prompt 에 적어요.

응답 · 상태#

status 는 queued → in_progress → completed 또는 failed 넷 중 하나예요. 만들기가 접수되면 HTTP 200 으로 조회와 같은 모양의 작업이 와요(머리글 openai-poll-after-ms: 5000 — 만들기 응답엔 늘 붙고, 조회 응답엔 끝나기 전까지만 붙어요) — status 는 보통 in_progress 이고, AI 회사가 받았는지 아직 모르면 queued 예요. queued · in_progress 면 끝날 때까지 조회만 하세요(까닭은 아래 「값은 어떻게 매겨지나요」). 끝나면 usage 칸에 초 · 해상도 · 실제로 뗀 값(cost_credits · 정수 크레딧)이 붙어요 — 실패로 끝난 작업도 usage 가 오고 cost_credits 는 0 이에요(만드는 도중 입력이 막힌 것만 그 값). queued · in_progress 동안엔 usage 가 null 이에요. 실패하면 error.code 로 이유를 말씀드려요(error 는 {"code", "message"} 이고 message 는 저희가 쓴 한국어 안내 문장이에요 — 분기는 code 로 하고, 학생 같은 최종 사용자 화면엔 message 를 그대로 보이지 말고 code 마다 직접 쓴 문장을 보여 주세요. moderation_blocked 도 안전 기준 · 저작권 · 실존 인물 가운데 무엇에 걸렸는지 가르는 칸은 없어요) — moderation_blocked(안전 기준 · 저작권 · 실존 인물 같은 내용 거절 — 접수 때든 만드는 중이든 · 같은 내용으로 다시 보내지 말고 고쳐서) · not_started(AI 회사에 보내기 전에 멈춤 · 요금 없음 — 보통 목록에서 보여요. 드물게 만들기 응답으로 오면 같은 Idempotency-Key 값 · 같은 본문으로 다시 보내세요 — 새로 만들어요) · vendor_failed · timed_out · undelivered, 이 다섯 중 하나로만 와요. AI 회사가 접수 때 거절하면 만들기 응답이 HTTP 200 에 status 가 바로 failed 예요 — status 부터 보세요. 만들기 응답의 status 가 벌써 failed 면 조회하지 말고 그 자리에서 error.code 로 가르세요. 만들기 전 거절은 HTTP 오류예요(몸통은 {"error": {"type", "code", "message", "reason", "request_id"}} 이고 code 는 type 과 같은 값 · reason 은 갈래가 있을 때만 와요 — 작업 객체의 error 와는 다른 자리예요): 400 invalid_request_error(칸 · 해상도 · 길이) · 401 authentication_error(키 — error.reason 이 까닭이에요 · 「인증」 장 「키가 안 열릴 때」 표) ·402 insufficient_credit(이 문의 error.reason 은 둘뿐이에요 — held_by_others 는 다른 키로 부른 것까지 같은 지갑의 다른 호출이 지갑 잔액을 잡아 둔 몫이라 Retry-After: 5 만큼 기다렸다 그대로 보내요. 같은 지갑에서 만드는 중인 영상이 잡은 몫이면 그 영상이 정산될 때 풀려서 보통 1분쯤 걸려요 — 몇 번 해도 같으면 그 영상이 끝난 뒤 보내세요. 그 영상이 성공하면 잔액이 그만큼 줄어 다음엔 hold_exceeds_balance 로 올 수 있어요 · hold_exceeds_balance 면 더 짧게 · 낮은 해상도로. below_minimum_balance 는 이 문엔 안 와요) · 403 student_key_blocked · model_not_in_plan · 404 model_not_found · 413(그림 파일 4MB 초과 · 본문 4.5MB 초과) · 429 key_limit_exceeded · group_limit_exceeded(영상 문의 429 는 이 둘뿐이고 error.reason 으로 갈라요 — "held_by_others" 만 x-should-retry: true · Retry-After: 5 라 그만큼 기다렸다 그대로 다시 보내요. 나머지 갈래는 모두 x-should-retry: false · Retry-After 없음이고, 하루 한도 · 강좌 몫은 같은 길이 · 해상도로 그대로 다시 보내면 같아요. 다시 열리는 시각은 몸통의 error.resets_at 이에요(UTC ISO 시각 · 다시 안 열리면 null · 「남은 한도」 장). 키 한도는 "held_by_others"(같은 키로 아직 끝나지 않은 호출(만드는 중인 영상 등) 몫까지 더하면 월 한도를 넘어요 — 만드는 중인 영상이면 풀리기까지 보통 1분쯤 걸려요. 그 영상이 실패로 끝나 요금이 안 붙으면 지나가고, 성공하면 잡아 둔 몫에 가까운 값을 떼서 다음엔 key_month_limit 으로 와요) · "key_month_limit"(월 · 쓴 몫과 이 영상 몫만으로 넘어요 — seconds 나 해상도를 줄이면 지나갈 수 있어요. 줄이거나 한도를 올리기 전엔 다음 달까지 같아요) · "key_day_limit"(하루 · 줄여도 같아요), 강좌 몫은 "group_budget"(seconds 나 해상도를 줄여 보세요 — 강좌 몫은 만드는 중인 영상 몫을 세지 않아서 앞 영상이 끝나길 기다려도 안 풀려요. 학기 누적 강좌(mode "total")는 resets_at 이 null 이라 다시 안 차요) · "group_closed" · "group_not_started" · "group_ended"(줄여도 같아요 — 「에러」 장)로 와요. 회사·기관 부서 몫이 끝에 닿았으면 "group_tail" 이에요(영상은 다음 달 1일에 다시 열려요 — 「에러」 장). 최종 사용자 화면엔 key_month_limit 을 「다 썼어요」로 옮기지 말고 「이번 달 남은 몫으로는 이 영상을 만들 수 없어요」처럼 써 주세요 — 남은 몫이 있어도 이 영상 몫 때문에 와요. vendor_failed 는 AI 회사가 요청을 받지 않았거나, 만들다 실패했거나, 몰려 거절한 것까지 다 이 코드예요 — HTTP 429 가 아니라 HTTP 200 · status failed 로 오고, 요금도 Retry-After 도 없어요. 그래서 최종 사용자 화면엔 「붐벼서」처럼 까닭을 단정하지 말고 「지금 영상을 만들지 못했어요. 잠시 뒤 다시 만들어 보세요」처럼 써 주세요. 잠시 뒤 새 Idempotency-Key 로 다시 만들고, 몇 번 해도 vendor_failed 면 글이나 그림을 바꿔 보세요 — 그래도 같으면 영상 id 와 부른 시각을 admin@schoolorder.kr 로 알려 주세요) · 503 api_error(Retry-After: 2 만큼 기다렸다 다시 — error.reason 이 provider_unavailable 이면 저희 쪽 사정으로 지금 그 모델에 요청을 넘기지 못한 거예요. 응답엔 작업 id 가 없지만 저희 쪽 작업은 요금 없이 닫혀 목록(GET /v1/videos)엔 error.code not_started 로 남고, 잠시 뒤 같은 Idempotency-Key · 같은 본문으로 다시 보내면 새로 만들어요. API 키를 잠깐 못 읽은 503(「지금 이 키를 확인하지 못했어요」)도 Idempotency-Key 를 실었든 아니든 Retry-After: 2 가 붙고 x-should-retry 는 없어요). 조회 · 받기의 503 · 409 엔 Retry-After 가 없어요 — 5초쯤 기다렸다 같은 주소를 다시 불러요. 503 을 받았다고 새 Idempotency-Key 로 다시 만들면 앞 영상도 끝나는 대로 값이 매겨져 두 편 값이 나가요. 스페이스 키는 전송 정책에 따라 space_content_policy 가 올 수 있어요(403 · 400 · 409 는 정책이 바뀐 것이라 확인 뒤 다시 · 503 은 잠시 뒤 다시). 영상 문(/v1/videos)의 Idempotency-Key 는 글 문과 달라요 — 같은 지갑에서 같은 값을 다시 보내면 본문(prompt · 모델 · 길이)이 달라도, 같은 지갑의 다른 API 키로 보내도 새로 만들지 않고 처음 작업을 돌려줘요(409 도 조회 주소도 없어요). 돌려주는 건 API 로 만든 영상뿐이에요 — 같은 지갑의 원포트 채팅이 만든 영상과 값이 겹치면 그 영상은 오지 않고 503 이 이어져요. 그래서 영상마다 새 값(uuid)을 쓰세요 — uuid 는 채팅 값과 겹치지 않아요. 처음 작업이 실패로 끝났어도 같은 값이면 그 실패 작업이 와요 — 값은 기한 없이 그 작업에 묶여요. 같은 값으로 돌아온 실패 작업 가운데 값이 풀리는 건 AI 회사에 보내기 전에 멈춘 작업(error.code not_started)뿐이라, moderation_blocked · vendor_failed · timed_out · undelivered 를 다시 만들 땐 새 값을 써요. 만들기 응답이 4xx 거절(400 · 401 · 402 · 403 · 404 · 409 · 413 · 429 — 409 는 스페이스 키의 space_content_policy 뿐이에요)이면 이 값을 묶지 않아요 — 고친 요청에 같은 값을 써도 새로 만들어요. 만들기 응답이 작업 id 없이 503(api_error · 스페이스 키는 space_content_policy)으로 오면 같은 값 · 같은 본문으로 그대로 다시 보내세요 — AI 회사에 보내기 전에 멈췄으면 새로 만들고, 이미 접수됐으면 그 작업이 와서 두 번 만들어지지 않아요. AI 회사가 접수 때 거절했는데 저희가 그 결과를 두 번 잇달아 못 적었을 때도 이 503 이 오고, 같은 값으로 다시 보내면 새로 만들어요 — 그 거절된 작업은 목록에 남았다가 요금 없이 vendor_failed 로 닫히는데, 닫힐 때까지(길게는 45분) 그 몫이 잡혀 있어요. 한 번만 못 적었으면 그 자리에서 다시 적어서 503 없이 그 실패 작업이 와요(2026-10-30 부터). error.reason 이 provider_unavailable 인 503 도 그 작업은 요금 없이 닫혀서 같은 값으로 다시 보내면 새로 만들어요. 보내기 전에 멈춘 작업은 보통 목록(GET /v1/videos)에서만 error.code not_started 로 보여요(요금 없음). 만들기 요청이 응답 없이 끊겨도 503 처럼 같은 값 · 같은 본문으로 다시 보내세요 — 작업이 이미 섰으면 그 작업이 와서 두 편이 생기지 않아요. 실패한 영상은 크레딧을 쓰지 않아요. 예외는 하나예요 — 만드는 도중 AI 회사가 입력(문장 · 그림)을 안전 기준으로 막고 값을 매기면 그만큼 크레딧을 사용하고, usage.cost_credits 에 그 값이 보여요. 그 값도 만들 때 미리 잡은 몫을 넘지 않아요. 같은 moderation_blocked 라도 접수 때 막힌 것과 만든 영상이 걸러진 것은 0 크레딧이고, 만드는 도중 입력이 막힌 것만 값이 붙어요 — error.code 로는 못 가르니 요금은 usage.cost_credits 로 보세요(지금 이 예외는 grok-imagine-video 계열과 runway-gen4.5 에서 나요). 접수 때 막힌 것 · 만든 영상이 걸러진 것(둘 다 moderation_blocked) · not_started · vendor_failed · timed_out · undelivered 는 0 크레딧이에요.

만드는 동안 progress 는 0~99 이고, completed 면 100 이에요. Seedance 모델은 끝날 때까지 0 이에요. 영상 모델 줄은 GET /v1/models 의 data[].kind 가 "video" 예요(endpoint 는 "POST /v1/videos"). 그 줄의 data[].pricing.video 에 min_seconds · max_seconds(숫자) · resolutions · aspect_ratios · supports_audio · default_generate_audio · input_image · retention_days(보관 일수 · 숫자) 가 있어요 — Runway 줄엔 text_aspect_ratios(글만 보낼 때 화면비) · prompt_max_characters · attribution(아래 「이 문이 받는 모델」)도 와요. resolutions 는 ["480p", "720p"] 처럼 해상도 글자, aspect_ratios 는 ["16:9", "9:16", …] 처럼 화면비 글자예요 — 초당 값은 pricing.rates 에서 dimension 이 video_<해상도>(예: video_720p)인 줄이에요. input_image 는 글자예요 — "optional_https_url_or_data_uri"(파일 · data URI · https 주소 다 돼요) · "optional_data_uri"(파일이나 data URI 만) · "required_https_url_or_data_uri"(그림이 꼭 있어야 해요) · "unsupported"(그림을 안 받아요). 시작 그림을 넣을 땐 "unsupported" 인 모델을 빼세요. 만든 지 45분이 지나면 끝나지 않은 작업을 닫아요 — queued 로 45분 머물면(AI 회사가 요청을 받았는지 저희가 확인하지 못한 드문 경우) vendor_failed, in_progress 로 45분이 지나면 timed_out 이에요. AI 회사는 다 만들었는데 파일이 3분 안에 저희 저장소에 안 오거나, 사용량으로 값을 매기는 모델(Seedance 등)에서 AI 회사가 사용량을 돌려주지 않아 값을 셀 수 없으면 undelivered 예요 — 값을 매기지 못한 영상을 따로 알리는 코드는 없어요. 셋 다 요금이 안 붙고, 다시 만들 땐 새 Idempotency-Key 를 써요. 다만 grok 계열은 queued 인 작업도 45분 안에 영상이 저희 저장소에 도착하면 completed 가 되고 값이 매겨져요. 조회(GET /v1/videos/{id}) · 받기(GET /v1/videos/{id}/content)는 요금이 없어요. 오류는 401(키) · 404 not_found_error(없는 id · 다른 지갑의 영상 · 학생 키면 다른 키가 만든 영상) · 503 api_error(저희가 작업을 잠깐 못 읽었어요 — 잠시 뒤 같은 주소를 다시 불러요)예요 — 받기는 아직 만드는 중이면 409 예요. 저희가 작업을 못 읽었을 땐 404 가 아니라 503 이 와요. 그래서 조회의 404 는 그 id 가 이 키로 볼 수 있는 영상이 아니라는 뜻이에요. 받기는 만들지 못한 영상 · 지운 영상에도 404 예요 — 받기가 404 면 먼저 조회로 status · expires_at 을 보세요. 작업 객체엔 prompt 가 와요(지웠거나 보관 기간 7일이 지나면 null) — Idempotency-Key 는 안 오니 영상 id 를 꼭 적어 두세요.

끝난 작업 (줄임)
{
  "id": "video_0f8fad5b-d9cb-469f-a165-70867728950e",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "prompt": "종이배가 잔잔한 호수 위를 떠가는 모습",
  "seconds": "4",
  "size": "1280x720",
  "created_at": 1790000000,
  "completed_at": 1790000031,
  "expires_at": 1790604831,
  "error": null,
  "usage": { "seconds": 4, "resolution": "720p", "cost_credits": 258 }
}

값은 어떻게 매겨지나요#

만들기를 부르는 순간 「초 × 해상도의 초당 값」을 먼저 잡아둬요. 끝나면 벤더가 실제로 매긴 값을 그 모델의 차감 단가로 셈해 떼요. 아래 표의 초당 값은 반올림한 값이고 더 자세한 값(소수 둘째 자리)은 GET /v1/models 의 pricing.rates[].credits 예요(항목은 {"dimension": "video_720p", "unit": "second", "unit_label": "second", "credits": 64.39} 모양 · grok-imagine-video 10-26 값 · 토큰으로 값을 매기는 Seedance 줄엔 16:9 · 24fps 로 어림한 값이라 "estimated": true 가 붙어요). grok-imagine-video 계열은 입력 그림이 있으면 그 몫을 조금 더 잡아요(예약 때 한 장에 9 크레딧 안팎 · 실제로 사용하는 값은 벤더가 매긴 만큼이라 보통 더 적어요). 예: grok-imagine-video 6초 720p + 그림 한 장이면 약 396 크레딧을 잡아 두고, 끝나면 그보다 적게 사용해요(10월 기준 · 정본은 GET /v1/models). usage.cost_credits 는 1 크레딧 아래를 올린 정수예요 — 미리 셈할 때도 「초 × credits」를 올려서 보세요. 예: 같은 모델 8초 720p 는 약 515.1 크레딧을 잡아 두고, 다 만들면 그 안에서 떼요. 그래도 usage.cost_credits 는 516 이에요 — 잡은 값보다 많이 뗀 게 아니에요(10월 기준 · 정본은 GET /v1/models). grok 계열 · Runway 는 잡는 값 = 초 × pricing.rates 의 video_<해상도> credits 예요(grok 계열은 그림이 있으면 약 9 를 더해요 · Seedance · Runway 는 그림 몫이 없어요). Seedance 는 잡는 값이 「초 × credits」보다 한 프레임 몫(credits 의 1/24쯤) 커요 — 끝나면 AI 회사가 돌려준 토큰으로 떼요. 9:16 은 16:9 와 같은 값을 잡아요 — Seedance 는 1:1 도 720p · 1080p 에선 16:9 와 같고, 4:3 · 3:4 는 720p · 1080p 에서 1% 안쪽으로 더, 480p 에선 1:1 · 4:3 · 3:4 가 조금 덜 잡아요. Gemini Omni 는 초당 값에 입력 · 생각 몫을 조금 더 잡아 두고, 끝나면 그 호출이 실제로 쓴 토큰(입력 · 영상 · 생각)으로 떼요. 뗀 값은 잡아둔 값을 넘지 않아요. 잡아둔 값은 잔액(balance_credits)에 바로 반영되지 않고 다른 호출이 쓸 몫만 줄여요. 끝나면 뗀 값만 크레딧을 사용하고 나머지는 풀려요. 벤더가 만들지 못하면 떼지 않아요. 45분 안에 끝난 영상은 조회하지 않아도 크레딧을 사용해요(저희가 따로 확인해 정산해요). 45분이 지나 확인했을 때 아직 만드는 중이면 timed_out 으로 닫고 떼지 않아요. 그래서 조회는 status 가 completed 나 failed 로 바뀔 때까지 이어 주세요 — 만든 지 45분이 지나면 닫히니 넉넉히 50분까지 보면 돼요(보통 1분 안에 끝나요). grok 계열에서 queued 를 받았거나, 어느 모델이든 조회를 일찍 멈췄다고 새 Idempotency-Key 로 다시 만들면, 앞 영상도 끝나는 대로 값이 매겨져 두 편 값이 나가요. 잡아둘 값보다 쓸 수 있는 잔액이 적으면 402 insufficient_credit, 키 한도를 넘으면 429 key_limit_exceeded 예요 — 둘 다 작업을 만들기 전이라 요금이 안 붙어요. API 키로는 동시에 만드는 편수에 상한이 없어요 — 잡아 둘 몫이 남는 만큼 보내져요. 키 월 한도는 정산이 끝난 몫에 이 키로 아직 끝나지 않은 몫(만드는 중인 다른 영상 포함)과 이 영상 몫을 더해 재요 — 그래서 여러 편을 한꺼번에 보내도 월 한도를 넘겨 접수되지 않고(같은 키로 글 호출도 같이 돌면 그 호출이 정산되는 순간과 겹쳐 호출 하나 몫쯤 넘을 수 있어요 · 「남은 한도」 장), 넘게 되는 편이 429(error.reason held_by_others)로 와요. 동시에 보낸 편은 보낸 차례가 아니라 저희 쪽에서 몫을 잡는 단계에 먼저 닿은 차례로 재요 — 어느 편이 이번 달 몫에 들어갈지 정하려면 접수를 하나씩 보내세요(접수는 몇 초예요). GET /v1/key 의 남은 몫엔 만드는 중인 영상 몫이 빠져 있어서(「남은 한도」 장), 남은 몫 ÷ 한 편 몫보다 덜 들어갈 수 있어요. 월 한도와 달리 하루 한도는 정산이 끝난 오늘 몫만 봐요(이 영상 몫도 더하지 않아요) — 그 몫이 한도에 닿아야 막아서, 마지막 한 편과 그때 만드는 중인 편들만큼은 넘을 수 있어요. 키 한도는 대시보드 AI API 화면 키 목록의 「한도 수정」(월 · 하루 · 기한)이나 관리 키의 PATCH /v1/keys/{id} 로 걸어요(스페이스 강좌 키 · 개인 API 키는 스페이스 관리자가 정해요).

여러 컷 이어 만들기#

한 번에 한 컷이에요. 긴 장면은 컷을 차례로 만들어 이어 붙여요. ① 컷마다 POST /v1/videos 에 시작 그림 한 장(input_reference 또는 image_url)을 넣어요. ② 끝나면 GET /v1/videos/{id}/content 로 mp4 를 받아, 마지막 프레임을 jpeg 로 뽑아요(예: ffmpeg -sseof -0.05 -i a.mp4 -frames:v 1 last.jpg). ③ 그 jpeg 를 data:image/jpeg;base64,… 로 다음 컷의 시작 그림에 넣어요 — Seedance · Runway · Grok · Gemini Omni 모델 모두 data URI 를 그대로 받아요. ④ 다 받은 mp4 를 순서대로 이어 붙이는 건 손님 쪽 일이에요(저희가 이어 붙여 드리지 않아요). 모든 영상 모델이 시작 그림을 한 장만 받아요 — 두 장 이상(끝 장면 지정 · 참고 그림 여러 장)은 400 이에요.

인물이 컷마다 흐트러지면 둘을 섞어요 — 앞 컷의 마지막 프레임을 image 첫 장(고칠 원본)으로, 인물 그림을 둘째 장(참고 그림)으로 POST /v1/images/edits 에 넣어 다음 컷의 시작 그림을 만들어요(칸과 그림 모델 id 는 https://oneport.kr/docs/reference/images.md 에 있어요). 그림 문은 여러 장을 받아요(grok-imagine-image 계열은 5장까지). dreamina-seedance-2-0 · -fast · -mini 는 시작 그림을 첫 장면(first_frame)으로 넘겨요. dreamina-seedance-2-5-260628 은 시작 그림을 첫 장면이 아니라 참고 그림으로 넘겨서, 앞 컷 마지막 장면에서 딱 이어지지 않을 수 있어요. 값은 컷마다 따로예요. grok-imagine-video 계열은 시작 그림을 넣으면 입력 그림 한 장 몫을 더 잡고, Seedance · Runway 는 그림 수와 상관없어요. Gemini Omni 는 그림을 시작 장면이 아니라 참고로 쓸 수 있어요(지시대로 모델이 정해요) — 첫 장면에서 이어 가려면 prompt 에 「이 그림에서 시작해」라고 적어 주세요.

이 문이 받는 모델#

한 편 값은 표 값을 곱하지 말고 위 「값은 어떻게 매겨지나요」대로 셈하세요. runway-gen4.5 로 만든 영상을 화면에 보일 땐 「Powered by Runway」 표기를 같이 보여 주세요 — GET /v1/models 의 그 줄 pricing.video.attribution 에 label · url · display_in_user_interface(true)로 와요. Seedance 는 워터마크를 넣지 말라고(watermark: false) 요청해요(결과는 벤더 동작).

영상

영상 모델 차감 단가(크레딧)
모델차감 단가
grok-imagine-videoGrok Imagine Video480p 50 크레딧 / 초 · 720p 70 크레딧 / 초
grok-imagine-video-1.5Grok Imagine Video 1.51080p 249 크레딧 / 초 · 480p 80 크레딧 / 초 · 720p 140 크레딧 / 초
dreamina-seedance-2-0-260128Seedance 2.01080p 373 크레딧 / 초 · 480p 70 크레딧 / 초 · 720p 151 크레딧 / 초
dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast480p 56 크레딧 / 초 · 720p 121 크레딧 / 초
dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini480p 35 크레딧 / 초 · 720p 75 크레딧 / 초
dreamina-seedance-2-5-260628Seedance 2.51080p 567 크레딧 / 초 · 480p 107 크레딧 / 초 · 720p 230 크레딧 / 초
runway-gen4.5Runway Gen-4.5720p 120 크레딧 / 초