모델

Reference-to-Video API: 이미지·영상·오디오 레퍼런스

POST /v1/videos에 input_references를 보내 레퍼런스 이미지, 영상, 오디오로 클립의 방향을 잡으세요. 유형별로 이를 받는 Sume 영상 모델과 받는 개수를 정리했습니다.

읽는 시간 5분Sume
전체 글

Sume API에서 레퍼런스 미디어로 영상의 방향을 잡으려면 image_url, video_url, audio_url 항목으로 이루어진 input_references 배열을 담아 POST /v1/videos를 보내세요. 모델은 레퍼런스를 정확한 프레임이 아니라 스타일이나 콘텐츠 가이드로 쓰며, 카탈로그 항목의 supported_input_references에 나열된 유형만 받습니다.

요청 형태는 영상 생성 문서 (영문)에서 가져왔습니다. 모델별 유형과 한도는 GET /v1/videos/models가 제공하는 카탈로그와 POST /v1/videos가 실행하는 검사에서 2026-09-26에 확인했습니다.

레퍼런스 이미지, 영상, 오디오는 어떻게 보내나요?

각 항목은 { "type": "video_url", "video_url": { "url": "…" } }처럼 type을 지정하고, 같은 이름의 키 아래에 URL을 넣습니다. 아래 요청은 문서의 레퍼런스로 영상 만들기 예제에 이미지와 함께 영상 레퍼런스를 추가한 것입니다.

  • 레퍼런스 URL은 공개 HTTPS여야 합니다. localhost, 사설 네트워크 URL, HTTPS가 아닌 URL, 서명된·비공개 URL은 제출 전에 거부됩니다.
  • frame_images는 빼세요. 요청에 둘 다 있으면 frame_images가 우선하고, 요청은 이미지로 영상 만들기가 되며, 레퍼런스는 쓰이지 않습니다. 프레임은 첫 프레임과 마지막 프레임을 지정하는 Image-to-Video API에서 다룹니다.
curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: r2v-001" \
  -d '{
    "model": "seedance-2",
    "prompt": "A colossal solar flare beside a planet",
    "input_references": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/style-ref.png" }
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/motion-ref.mp4" }
      }
    ],
    "resolution": "1080p"
  }'

어떤 모델이 이미지, 영상, 오디오 레퍼런스를 받나요?

Seedance 2.x, Wan 3.0, MiniMax H3, MiniMax H3 Max는 세 유형을 모두 받습니다. Gemini Omni Flash 1.1은 이미지와 영상은 받지만 오디오는 받지 않습니다. kling-3, grok-imagine-video-1.5는 레퍼런스를 받지 않습니다.

레퍼런스 유형은 GET /v1/videos/models가 제공하는 카탈로그와 영상 생성 (영문) 기준, 개수는 POST /v1/videos의 검사와 GET /v1/video-router/models/{model_id}에 나온 모델별 constraints 기준, 2026-09-26 확인. 제출하기 전에 GET /v1/videos/models로 확인하세요.
모델 ID이미지영상오디오한도
seedance-2.5, seedance-2, seedance-2-fast, seedance-2-mini예예예레퍼런스 합계 최대 12개
wan-3.0예예예이미지 ≤ 10개; 영상 ≤ 5개(합계 ≤ 15초, ≥ 16 fps); 오디오 ≤ 5개(합계 ≤ 15초)
minimax-h3, minimax-h3-max예예예이미지 ≤ 9개; 영상 ≤ 3개, 오디오 ≤ 3개, 각각 2–15초, 유형별 합계 ≤ 15초; 전체 ≤ 12개. 오디오만 레퍼런스로 보낼 수 없음
gemini-omni-flash-1.1예예아니요이미지 ≤ 10개; 영상 ≤ 3개, 각 ≤ 3초
kling-3아니요아니요아니요레퍼런스 없음
grok-imagine-video-1.5아니요아니요아니요레퍼런스 없음

모델이 받지 않는 유형이나 개수를 보내면 어떻게 되나요?

POST /v1/videos는 요청을 400으로 거부합니다. 모델이 받지 않는 유형이나 유형별 개수를 보내면 오류 코드 unsupported_capability와 함께 그 한도를 밝히는 메시지가 반환됩니다.

  • 모델이 나열하지 않은 유형: “kling-3 does not support input_references type image_url.”
  • 한 유형의 개수 초과: “wan-3.0 accepts at most 5 video input_references.”
  • 전체 레퍼런스가 12개를 넘으면 이 검사까지 가지 않습니다. 요청 본문 자체가 input_references를 최대 12개까지만 허용하므로, 13번째 레퍼런스는 invalid_request로 실패합니다.

모델별 레퍼런스 규칙이 따로 있나요?

두 모델 계열에는 자체 규칙이 더 있습니다.

  • Gemini Omni Flash 1.1: 프롬프트에서 레퍼런스 미디어를 <IMAGE_REF_0>, <VIDEO_REF_0> 형식으로 가리키세요. 번호는 목록 순서대로 0부터 셉니다. 레퍼런스 영상은 새 클립의 방향을 잡습니다. 기존 클립을 바꾸려면 편집 원본을 별도의 video_url 필드로 보내며, 이는 프롬프트로 영상 편집하기에서 다룹니다.
  • MiniMax H3와 H3 Max: 오디오에는 이미지나 영상 레퍼런스를 하나 이상 함께 보내세요.

Video Router에서는 레퍼런스가 어떻게 동작하나요?

레거시 POST /v1/video-router/generate 경로는 바뀌지 않고 계속 동작하며, 레퍼런스를 reference_image_urls, reference_video_urls, reference_audio_urls라는 평면 URL 배열로 받습니다. 이 경로의 검사는 두 군데에서 다릅니다. 여기서 Seedance 2.x는 최대 이미지 9개, 영상 3개, 오디오 파일 3개까지 받고, 모든 모델에서 오디오에는 이미지나 영상 레퍼런스가 하나 이상 필요합니다. 새 연동에는 /v1/videos를 쓰세요. 스틸 이미지의 경우 POST /v1/images도 input_references를 받습니다. 레퍼런스 이미지 기반 이미지 생성 API를 참고하세요.

레퍼런스로 영상 만들기 Job의 요금은 어떻게 청구되나요?

영상 Job은 모든 모델에서 제출 시 공급사 정가 × 1.25로 예약되고, 기본 5.5% 에이전트 수수료가 더해집니다. 요율은 GET /v1/videos/models의 pricing_skus에 있습니다. API 요금도 참고하세요.

카탈로그에서 눈여겨볼 점이 두 가지 있습니다. minimax-h3에서는 처음 다섯 장의 레퍼런스 이미지에는 추가 요금이 없고 그 뒤의 이미지는 한 장마다 요금이 더해지며, minimax-h3-max는 레퍼런스로 영상 만들기를 출력 초 단위로 청구합니다.

출처

관련 글

작성자 Sume