---
title: "Generate video toward a strict last frame"
method: POST
path: "/v1/videos/frames-to-video"
tags: ["videos"]
---

# Generate video toward a strict last frame

`POST /v1/videos/frames-to-video`

## Request

- Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.beatra.ai/v1/videos/frames-to-video`
- Auth: none declared. Required headers: `Idempotency-Key`

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

## Headers

- `x-request-id` string, nullable
- `Idempotency-Key` string, required
- `authorization` string, nullable

## Request body

- FramesToVideoRequest
  - `metadata` object, nullable: Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars
  - `callback_url` string, nullable: HTTPS URL beatra will POST the final Task envelope to when the Task reaches a terminal state
  - `callback_signing_key_id` string, nullable: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.
  - `model` 'auto' | 'minimax-h3' | 'wan3.0-video' | 'wan3.0-video-prime' | 'wan2.7-i2v' | 'seedance-2' | 'seedance-2-fast' | 'seedance-2-mini' | 'seedance-2.5': Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted.
  - `negative_prompt` string, nullable: Content or qualities to avoid when supported by the selected model.
  - `duration` union: Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default.
    - integer
    - 'auto'
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '4:5' | '5:4' | '21:9' | '9:21' | 'adaptive', nullable: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior.
  - `resolution` '480p' | '720p' | '1080p' | '2k' | '4k', nullable: Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced.
  - `seed` integer, nullable
  - `enhance_prompt` boolean, nullable: Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
  - `watermark` boolean, nullable: Whether generated video should include the model watermark.
  - `generate_audio` boolean, nullable: Whether the selected model should generate synchronized audio.
  - `web_search` boolean, nullable: Whether the selected model may use web search during generation.
  - `return_last_frame` boolean, nullable: Whether to return the generated video's last frame as an image artifact.
  - `output_format` 'mp4' | 'mov', nullable: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding.
  - `prompt` string, nullable: Optional instructions for the motion ending at the required last frame.
  - `first_frame` union: Optional image that must be the video's first frame. Omit it for a last-frame-only request when the selected model advertises that input combination.
    - MediaInputUrl
      - `type` 'url', required
      - `url` string, required: HTTPS URL. External URLs are downloaded and re-hosted to beatra CDN.
    - MediaInputArtifact
      - `type` 'artifact', required
      - `artifact_id` string, required: ULID of a previously-uploaded artifact
    - MediaInputDataUri
      - `type` 'data_uri', required
      - `data` string, required: Data URI (e.g. data:image/png;base64,...) — max 256KB encoded
  - `last_frame` union, required: Required image that must be the video's last frame.
    - MediaInputUrl
      - `type` 'url', required
      - `url` string, required: HTTPS URL. External URLs are downloaded and re-hosted to beatra CDN.
    - MediaInputArtifact
      - `type` 'artifact', required
      - `artifact_id` string, required: ULID of a previously-uploaded artifact
    - MediaInputDataUri
      - `type` 'data_uri', required
      - `data` string, required: Data URI (e.g. data:image/png;base64,...) — max 256KB encoded
  - `driving_audio` union: Optional driving audio. Supplying it requires a model that supports this control.
    - MediaInputUrl
      - `type` 'url', required
      - `url` string, required: HTTPS URL. External URLs are downloaded and re-hosted to beatra CDN.
    - MediaInputArtifact
      - `type` 'artifact', required
      - `artifact_id` string, required: ULID of a previously-uploaded artifact
    - MediaInputDataUri
      - `type` 'data_uri', required
      - `data` string, required: Data URI (e.g. data:image/png;base64,...) — max 256KB encoded

## Response `202`

Task accepted

- TaskEnvelope: Standard Task envelope. Returned by every async-creation endpoint, GET /v1/tasks/{id}, and the body of customer callback POSTs.
  - `object` 'task'
  - `task_id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `capability` string, required
  - `workload_type` 'model' | 'social_operation'
  - `model` string, nullable: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks.
  - `resolved_model` string, nullable: Actual model that ran (null until execution starts; equals model for explicit-model calls)
  - `model_selection_reason` unknown
  - `social` SocialTaskIdentity
    - `platform` string, required
    - `operation_key` string, required
    - `operation_name` string, required
    - `schema_hash` string, required
  - `metadata` object, nullable
  - `input` object, nullable
  - `progress` AppApiV1SchemasCommonTaskProgress
    - `percent` integer, nullable
    - `stage` string, nullable
    - `message` string, nullable
  - `output` object, nullable
  - `warnings` TaskWarning[]
    - `code` string, required: e.g. option_clamped / auto_routed
    - `message` string, required
    - `field` string, nullable
  - `error` AppApiV1SchemasCommonTaskError
    - `code` string, required: Stable machine-readable public error code.
    - `type` string, required: Stable public error family.
    - `message` string, required: Human-readable safe failure reason.
    - `retryable` boolean, required: Whether the same logical request may succeed when retried unchanged.
    - `param` string, nullable: JSON Pointer to the relevant request or output field.
    - `details` object, nullable: Provider-neutral expected, received, supported, or candidate failure facts.
    - `request_id` string, required: Request trace identifier for support and correlation.
  - `usage` UsageObject
    - `input_tokens` integer, nullable
    - `output_tokens` integer, nullable
    - `cache_read_tokens` integer, nullable
    - `cache_creation_tokens` integer, nullable
    - `reasoning_tokens` integer, nullable
    - `image_count` integer, nullable
    - `image_pixels` integer, nullable
    - `video_seconds` number, nullable
    - `input_video_seconds` number, nullable: Authoritative input-video seconds included in settled video usage.
    - `output_video_seconds` number, nullable: Authoritative generated/output-video seconds included in settled video usage.
    - `audio_seconds` number, nullable
    - `characters` integer, nullable
    - `lines` UsageLine[]
      - `meter` string, required: e.g. input_token / output_token / image_count / input_video_second / output_video_second
      - `quantity` string, required: Decimal — number of meter units consumed
      - `unit` string, required: Display unit, e.g. 'token' / 'image' / 'second'
      - `billed_amount_credits` string, nullable: Credits charged for this usage line. Populated by PR-2/3.
    - `credits` string, nullable: Credits charged for this Task. Populated by PR-2 / PR-3.
  - `billing` TaskBilling
    - `charged_credits` string, nullable: Credits charged to wallet for this Task. Populated by PR-2/3.
    - `refunded_credits` string, nullable: Credits refunded for this Task. Populated by PR-3.
    - `granted_credits` string, nullable: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied.
    - `grant_source` string, nullable: Which grant covered it. Present exactly when granted_credits is.
    - `net_charged_credits` string, nullable: Final customer charge: charged_credits minus refunded_credits minus granted_credits. This is the number to report as what the Task cost.
  - `callback` TaskCallback
    - `url` string, required
    - `status` 'pending' | 'dispatching' | 'delivered' | 'retrying' | 'failed', required
    - `attempt_count` integer, required
    - `delivered_at` string, date-time, nullable
    - `last_error` string, nullable: Stable Beatra-owned callback delivery failure summary.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `links` TaskLinks, required
    - `self` string, required
    - `cancel` string, nullable
    - `assets` string, nullable: Absolute customer-console URL for viewing and managing the generated artifacts.

## Other responses

- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)