Beatra

Generate video between strict first and last images

Create an asynchronous video task constrained by required first-frame and last-frame images. Use image-to-video when only the opening frame must be fixed.

POST
/v1/videos/frames-to-video

Request Body

application/jsonRequired
metadataMetadata

Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars

callback_urlCallback Url

HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state

callback_signing_key_idCallback Signing Key Id

Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.

modelModel

Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted.

Default: "auto"Value in: "auto" | "minimax-h3" | "wan2.7-i2v" | "seedance-2" | "seedance-2-fast" | "seedance-2-mini"
negative_promptNegative Prompt

Content or qualities to avoid when supported by the selected model.

durationDuration

Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default.

aspect_ratioAspect Ratio

Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior.

resolutionResolution

Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced.

seedSeed
enhance_promptEnhance Prompt

Ask the selected model to improve the prompt before generation.

watermarkWatermark

Whether generated video should include the model watermark.

generate_audioGenerate Audio

Whether the selected model should generate synchronized audio.

web_searchWeb Search

Whether the selected model may use web search during generation.

return_last_frameReturn Last Frame

Whether to return the generated video's last frame as an image artifact.

promptPrompt

Optional instructions for the motion between the two strict boundary frames.

first_frame
Required
First Frame

Required image that must be the video's first frame.

last_frame
Required
Last Frame

Required image that must be the video's last frame.

driving_audioDriving Audio

Optional driving audio. Supplying it requires a model that supports this control.

Header Parameters

X-Request-Idstring

Optional client request id echoed in the response.

Idempotency-Key
Required
Idempotency-Key
Minimum length: 1Maximum length: 128
Authorization
Required
string

Bearer API key.

curl -X POST "https://example.com/v1/videos/frames-to-video" \
  -H "X-Request-Id: string" \
  -H "Idempotency-Key: string" \
  -H "Authorization: string" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "callback_url": "string",
    "callback_signing_key_id": "string",
    "model": "auto",
    "negative_prompt": "string",
    "duration": 0,
    "aspect_ratio": "16:9",
    "resolution": "480p",
    "seed": 2147483647,
    "enhance_prompt": true,
    "watermark": true,
    "generate_audio": true,
    "web_search": true,
    "return_last_frame": true,
    "prompt": "string",
    "first_frame": {
      "type": "url",
      "url": "string"
    },
    "last_frame": {
      "type": "url",
      "url": "string"
    },
    "driving_audio": {
      "type": "url",
      "url": "string"
    }
  }'

Task accepted

{
  "object": "task",
  "task_id": "string",
  "status": "queued",
  "capability": "string",
  "model": "string",
  "resolved_model": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "input": {},
  "progress": {
    "percent": 100,
    "stage": "string",
    "message": "string"
  },
  "output": {},
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "error": {
    "code": "string",
    "type": "string",
    "message": "string",
    "retryable": true,
    "param": "string",
    "details": {},
    "request_id": "string"
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0,
    "reasoning_tokens": 0,
    "image_count": 0,
    "image_pixels": 0,
    "video_seconds": 0,
    "input_video_seconds": 0,
    "output_video_seconds": 0,
    "audio_seconds": 0,
    "characters": 0,
    "lines": [
      {
        "meter": "string",
        "quantity": "string",
        "unit": "string",
        "billed_amount_credits": "string"
      }
    ],
    "credits": "string"
  },
  "billing": {
    "charged_credits": "string",
    "refunded_credits": "string",
    "net_charged_credits": "string"
  },
  "callback": {
    "url": "string",
    "status": "pending",
    "attempt_count": 0,
    "delivered_at": "2019-08-24T14:15:22Z",
    "last_error": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "cancel_requested_at": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "cancel": "string"
  }
}