Recast 400 "exactly one source video and 1-4 images": five causes

The message "H3 Max Recast requires exactly one source video and 1-4 images in input_references; frame_images and audio references are not supported" is a 400 with the code unsupported_capability from POST /v1/videos. It means the request has zero or several videos, any audio reference, or any frame image. The fix is to send one video_url entry and one to four image_url entries, and nothing else.

The five ways to trigger it

Recast is a narrow contract. It swaps people in an existing clip, so it has no text-only mode and no first frame. Each of the cases below breaks the contract.

A correct request shape

On /v1/videos the video and the photos go together in input_references, using the same type / nested url shape as other reference images. On the Video Router the same inputs are flat fields: video_url and reference_image_urls. The duration is the inspected source length, and resolution is 768p unless you pass 1080p.

{
  "model": "h3-max-recast",
  "duration": 12,
  "resolution": "768p",
  "input_references": [
    {"type": "video_url", "video_url": {"url": "https://media.sume.com/artifacts/artf_demo/ad.mp4"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/new-presenter.jpg"}}
  ]
}

Other recast messages you may meet next

After the reference check passes, the same validator can answer with plain-language messages, and each names the field to change.

• "H3 Max Recast requires 1-4 reference image URLs, one per new person." : zero photos, five or more photos, or a photo URL that is not public HTTPS.
• "H3 Max Recast prompt must be at most 2000 characters."
• "H3 Max Recast resolution must be 768p or 1080p."
• "H3 Max Recast does not support aspect_ratio." (also generate_audio and bitrate_mode)
• "H3 Max Recast requires the inspected source video's duration (5-30 seconds)."

Cost of the mistake

A request that fails validation is refused before a job is reserved, so nothing is billed for it. A correct 12-second job is $4.50 at 768p, 12 x $0.30 x 1.25.

How to avoid the round trip

You can catch every one of these before the request. Count the items in your input_references list by type and reject the request in your own code when the video count is not one, when the image count is outside 1 to 4, or when any audio type is present. The same applies to the flat fields on the Video Router. Treat the error message as a diagnostic: it names the rule that was broken rather than the field, so you read it as a checklist. Because refused requests are not reserved or submitted, retrying with a corrected body is safe. Use an Idempotency-Key only on the corrected request so the retry is not mistaken for the failed one.

For teams that call the API from a queue worker, log the full error body with the request id, and map this error to a non-retryable state. A malformed recast request will fail the same way each time, so retrying in a loop only delays the fix. Once the body is corrected, the same job is priced from the source length and resolution like any other recast request.