---
title: "Create Video Generation"
method: POST
path: "/v1/video-generations"
tags: ["Public API"]
---

# Create Video Generation

`POST /v1/video-generations`

## Request

- Base URL: `https://api.animgen.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.animgen.com/v1/video-generations`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, nullable

## Request body

- VideoGenerationCreateRequest
  - `input` GenerationInput, required
    - `first_frame` union, required: Required starting image; use the type discriminator to select an input representation.
      - object
        - `type` 'file', required
        - `file_id` string, uuid, required: Owned public file ID from POST /files or complete_image_upload; not a Studio upload ID.
      - object
        - `type` 'base64', required
        - `media_type` 'image/png' | 'image/jpeg' | 'image/webp', required: Actual image MIME type.
        - `data` string, required: Pure Base64 without a data URL prefix; decoded limits: 10 MiB per image, 20 MiB total.
      - object
        - `type` 'url', required
        - `url` string, required: Public HTTPS image on port 443, without credentials or fragments. Private networks and unsafe redirects are rejected. Keep bytes stable across retries.
    - `last_frame` union: Optional end image; the selected model must support first/last-frame mode.
      - object
        - `type` 'file', required
        - `file_id` string, uuid, required: Owned public file ID from POST /files or complete_image_upload; not a Studio upload ID.
      - object
        - `type` 'base64', required
        - `media_type` 'image/png' | 'image/jpeg' | 'image/webp', required: Actual image MIME type.
        - `data` string, required: Pure Base64 without a data URL prefix; decoded limits: 10 MiB per image, 20 MiB total.
      - object
        - `type` 'url', required
        - `url` string, required: Public HTTPS image on port 443, without credentials or fragments. Private networks and unsafe redirects are rejected. Keep bytes stable across retries.
    - `reference_images` union[]: Additional references, excluding the first frame. The live model can impose a smaller limit.
      - union
        - FileImageInput
          - `type` 'file', required
          - `file_id` string, uuid, required: Owned public file ID from POST /files or complete_image_upload; not a Studio upload ID.
        - Base64ImageInput
          - `type` 'base64', required
          - `media_type` 'image/png' | 'image/jpeg' | 'image/webp', required: Actual image MIME type.
          - `data` string, required: Pure Base64 without a data URL prefix; decoded limits: 10 MiB per image, 20 MiB total.
        - UrlImageInput
          - `type` 'url', required
          - `url` string, required: Public HTTPS image on port 443, without credentials or fragments. Private networks and unsafe redirects are rejected. Keep bytes stable across retries.
  - `prompt` string: Motion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs.
  - `negative_prompt` string: Optional exclusions, only when the model supports negative prompts.
  - `video` VideoOptions
    - `model` string, nullable: provider:model ID from GET /models; omission uses the configured default model.
    - `duration_seconds` number, nullable: Seconds; choose a supported duration for the model and resolution. Omission uses its default.
    - `resolution` string, nullable: Resolution value from the live model catalog.
    - `ratio` string, nullable: Aspect ratio supported by the current model and input mode.
    - `seed` integer, nullable: Optional seed only for models advertising seed support; not a universal determinism guarantee.
    - `style_preset` string, nullable: Optional style preset supported by the selected provider/model.
    - `watermark` boolean, nullable: Optional watermark setting; check the model capability.
    - `transparency` GenerationTransparency
      - `mode` 'standard' | 'alpha_key': standard keeps the scene; alpha_key requires meaningful alpha in all active input images. Raw videos remain opaque.
      - `key_color` string, nullable: Temporary key color when using manual selection; normally leave automatic selection enabled.
      - `key_selection` 'auto' | 'manual': How the temporary key color is selected.
    - `input_canvas` object, nullable: Optional input framing; omit to keep the source framing.
      - `enabled` boolean: Whether to prepare an expanded input canvas.
      - `source_scale` number: Source subject scale within the canvas.
      - `position_x` number: Normalized horizontal source position.
      - `position_y` number: Normalized vertical source position.
      - `aspect_ratio` 'follow_output' | 'source': Follow the output ratio or preserve the source ratio.
      - `background` 'auto' | 'transparent' | 'solid': Canvas extension background strategy.
      - `background_color` string, nullable: Six-digit RGB color for a solid extension.
  - `metadata` object: Caller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets.

## Response `202`

Successful Response

- TaskResponse
  - `id` string, uuid, required: Persist this task ID immediately after create; poll it instead of creating again.
  - `object` 'video_generation' | 'animation_export' | 'animation', required: Public task resource type.
  - `status` 'queued' | 'running' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled', required: succeeded, failed, and cancelled are terminal; cancelling is not terminal.
  - `stage` 'queued' | 'video_generation' | 'animation_export' | 'completed', nullable: Current pipeline stage when available.
  - `progress` number, required: Fraction from 0 to 1, not a completion-time estimate.
  - `credits` CreditUsage, required
    - `quoted` integer, required: Quoted total, not necessarily the final charge.
    - `held` integer, required: Credits currently reserved, not an additional charge to sum with charged.
    - `charged` integer, required: Net charged credits. Confirmed provider moderation rejection is refunded; cancellation alone is not a refund.
    - `refunded` integer: Credits returned after a charge; already excluded from charged. Not a cash refund.
    - `released` integer: Credits returned from an uncommitted hold.
    - `status` string, nullable: Billing state: held, charged, released, refunded, or managed for internal child tasks.
  - `outputs` AssetResponse[]: Available assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state.
    - `object` 'asset'
    - `id` string, uuid, required: Stable public asset ID; use it to refresh download metadata.
    - `format` string, required: Artifact format; inspect actual outputs rather than assuming an array order.
    - `mime_type` string, required: Asset media type.
    - `byte_size` integer, required: Expected file size in bytes.
    - `created_at` string, date-time, required: Creation timestamp in UTC.
    - `download_url` string, required: Sensitive short-lived signed URL. Download without a Bearer header, including after redirects; never log the URL.
    - `download_expires_at` string, date-time, required: Signed URL expiry in UTC; refresh via asset lookup when expired.
    - `media` object, nullable: Whitelisted measured video metadata. Unknown fields are null; non-video assets return null.
      - `duration_seconds` number, nullable: Playable video duration measured from presentation timestamps; never provider-requested duration.
      - `fps` number, nullable: Measured average source frame rate; use presentation timestamps for VFR selection.
      - `frame_count` integer, nullable: Decoded source frame count, or null when unknown.
      - `width` integer, nullable: Displayed video width in pixels, accounting for rotation.
      - `height` integer, nullable: Displayed video height in pixels, accounting for rotation.
  - `metadata` object: Caller-provided metadata.
  - `normalized_input` object: Normalized public input; may contain private prompts or image references. Do not log wholesale.
  - `resolved_export` object, nullable: Persisted FPS sampling summary shared with the quote and manifest; null for legacy tasks.
    - `selection` Selection, required
      - `mode` 'full' | 'range': full uses the complete source; range requires duration_seconds.
      - `start_seconds` number: Range start in seconds from the source beginning.
      - `duration_seconds` number, nullable: Required when mode=range; positive interval length in seconds.
    - `fps` number, required: Target sampling frequency; never recalculated as frame_count / duration.
    - `frame_count` integer, required: Number of samples strictly before the selected end.
    - `duration_ms` integer, required: Sum of manifest frame durations in milliseconds.
    - `warnings` ExportWarning[]: Sampling warnings, including repeated source frames without interpolation.
      - `code` string, required
      - `message` string, required
      - `details` object
  - `error` object, nullable: Task failure details, independently of any usable outputs.
    - `code` string, required: Machine-readable task error code.
    - `message` string, required: Human-readable summary, not a stable branching key.
    - `retryable` boolean: Whether retry may help; inspect partial outputs before creating a new paid task.
    - `param` string, nullable: Related public parameter when available.
    - `details` object: Public error details, without private storage or provider values.
  - `created_at` string, date-time, required: UTC acceptance timestamp.
  - `started_at` string, date-time, nullable: UTC production start when known.
  - `finished_at` string, date-time, nullable: UTC terminal timestamp when known.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/animgen/apis/aianimgenbackend.md) · [All operations](https://skmtc.dev/animgen/apis/aianimgenbackend/llms.txt) · [OpenAPI document](https://skmtc.dev/animgen/apis/aianimgenbackend/revisions/ac3744fbb14e?raw)