2026-09-26개발자

영상 생성 API 400 오류: 지원되지 않는 파라미터와 해결법

POST /v1/videos 400 원인과 해결: invalid_request, unsupported_parameter(size·seed·provider.options), unsupported_capability.

읽는 시간 5분Sume

Sume의 POST /v1/videos가 400을 반환했다면 요청이 규칙을 어긴 것이며, 어떤 규칙인지는 error.code가 알려 줍니다. 본문이 요청 스키마를 통과하지 못하면 invalid_request, size·seed나 비어 있지 않은 provider.options를 보내면 unsupported_parameter, 값이 선택한 모델의 카탈로그 목록을 벗어나면 unsupported_capability입니다.

아래 코드는 Sume의 영상 생성 (영문) 문서와 오류와 요청 한도 (영문) 문서, 그리고 API의 요청 검증 로직에서 가져왔으며, 2026-09-26에 확인했습니다. 일반적인 오류 봉투, 다른 상태 코드, 429 응답은 Sume API 오류와 요청 한도에서 다룹니다.

POST /v1/videos는 어떤 400 오류를 반환하나요?

영상 요청에 특화된 거부는 코드 세 가지로 구분됩니다. 네 번째 실패인 알 수 없는 모델 ID는 400이 아니라 404입니다.

영상 생성 (영문), API 레퍼런스, API의 요청 검증 기준, 2026-09-26 확인. 모델별 목록은 `GET /v1/videos/models`로 확인하세요.
상태와 코드	원인	해결
`400 invalid_request`	본문이 요청 스키마를 통과하지 못함: 알 수 없는 필드, `prompt` 누락, 잘못된 URL, enum을 벗어난 값	`details.errors`에 나온 필드 수정
`400 unsupported_parameter`	`size`, `seed`, 또는 비어 있지 않은 `provider.options`	필드 제거. `size` 대신 `resolution`과 `aspect_ratio` 사용
`400 unsupported_capability`	모델의 카탈로그 항목에 없는 값, 또는 모델이 받을 수 없는 입력 조합	`details.supported`에서 값을 고르거나 해당 입력 제거
`404 model_not_found`	`model`이 카탈로그 ID도, `sume/auto` 같은 auto 별칭도 아님	`GET /v1/videos/models`에 나온 접두어 없는 ID 사용

unsupported_parameter 오류는 어떻게 고치나요?

요청 스키마에는 OpenRouter와 마찬가지로 이 필드들이 정의되어 있지만, 이를 반영할 수 있는 v1 모델은 없습니다. Sume는 이 필드를 조용히 버리지 않고 거부하며, 메시지마다 이유를 밝힙니다.

size: 모든 모델이 supported_sizes: null을 보고합니다. 대신 resolution과 aspect_ratio를 보내세요.
seed: 모든 모델이 seed: false를 보고합니다. 이 필드를 빼세요. 시드를 받는 v1 모델은 없습니다.
provider.options: 모든 모델에서 allowed_passthrough_parameters가 비어 있습니다. 생략하거나 {}를 보내세요.

unsupported_capability는 무슨 뜻인가요?

본문 형식은 올바르지만, 지정한 모델이 요청한 일을 할 수 없다는 뜻입니다. Sume는 요청을 모델의 카탈로그 항목과 대조하며, 이 항목은 GET /v1/videos/models를 만드는 원본입니다. 값이 목록을 벗어나면 오류의 details에 model, field, value, 그리고 허용 목록인 supported가 담깁니다. 흔한 원인은 다음과 같습니다.

모델 목록에 없는 duration, resolution, aspect_ratio. 예를 들어 네이티브 480p 또는 768p인 minimax-h3에 720p를 보내는 경우입니다.
supported_frame_images나 supported_input_references에 없는 frame_type 또는 input_references 유형.
first_frame 없이 보낸 last_frame.
한 유형의 레퍼런스를 모델이 받는 개수보다 많이 보낸 경우. 예를 들어 minimax-h3에 열 번째 이미지를 보내는 경우이며, 모델별 상한은 레퍼런스로 영상 만들기 가이드에서 비교합니다.
디스크립터가 generate_audio: false를 보고하는 모델에 보낸 generate_audio: true.
항상 오디오를 만드는 minimax-h3, minimax-h3-max, gemini-omni-flash-1.1에 보낸 generate_audio: false. 이 필드는 생략하세요.

왜 invalid_request가 반환되나요?

대개 모델 규칙을 확인하기도 전에 본문이 요청 스키마를 통과하지 못한 경우입니다. details.errors에는 문제마다 path와 message가 나열됩니다. 이 경로에서는 다음과 같은 경우입니다.

스키마에 정의되지 않은 최상위 필드.
모델을 고정했는데 prompt가 없는 경우.
모델을 고정한 요청에 넣은 image_url, end_image_url, reference_image_urls, video_url 같은 Video Router 필드. frame_images와 input_references를 쓰거나, 이런 플랫 필드는 POST /v1/video-router/generate로 보내세요.
공개 HTTPS가 아닌 미디어 URL이나 callback_url URL.
정수가 아닌 duration, 또는 스키마의 enum을 벗어난 resolution이나 aspect_ratio.
2개를 넘는 frame_images 또는 12개를 넘는 input_references.

오류 본문은 어떤 모양인가요?

Sume의 표준 봉투입니다. 봉투에는 retryable과 next_action도 들어 있으며, 400에서는 각각 false와 fix_input이므로 다시 보내기 전에 본문을 고치세요. 지원팀에 문의할 때는 request_id를 알려 주세요. 이 minimax-h3 예시에서 supported에는 모델 디스크립터에 빠져 있는 2K, 4K 업스케일도 나열됩니다.

{
  "error": {
    "code": "unsupported_capability",
    "message": "minimax-h3 does not support resolution 720p.",
    "request_id": "req_...",
    "details": {
      "model": "minimax-h3",
      "field": "resolution",
      "value": "720p",
      "supported": ["480p", "768p", "2K", "4K"]
    }
  }
}

거부된 요청도 과금되나요?

과금되지 않습니다. 위의 스키마 검사와 모델 검사는 Sume가 Job을 만들거나 잔액을 예약하기 전에 실행되므로, 이런 400은 Job도 요금도 남기지 않습니다. 다만 invalid_request 하나는 더 나중에 나옵니다. Sume가 Job을 공급사에 제출하는 중에 입력을 거부하면 Job이 이미 존재하므로, Sume는 그 Job을 실패로 표시하고 예약 금액을 환불한 뒤 details에 Job을 담아 반환합니다. 접수된 뒤 실행 중에 실패한 Job은 error 필드와 함께 status: failed를 반환하며, 이는 AI 영상 Job이 실패하는 이유에서 다룹니다.

출처

작성자 Sume