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

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는 레퍼런스를 받지 않습니다.

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

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는 레퍼런스로 영상 만들기를 출력 초 단위로 청구합니다.