Native Video Generation

The Light Speed Future video generation API follows an OpenAI-compatible style, but advanced Seedance controls such as duration, resolution, aspect ratio, first/last frame control, multimodal references, and the audio switch are passed under metadata. In practice, metadata is the most important part of this integration.

5.1 Supported Task Endpoints

• Submit a task: POST /v1/videos
• Retrieve a task: GET /v1/videos/{task_id}
• Typical status values: queued / in_progress / completed / failed / expired

Current task-management scope

Current scope: do not assume support for DELETE /v1/videos/{task_id}, GET /v1/videos, or POST /v1/videos/{task_id}/cancel unless those endpoints are separately enabled and confirmed by Light Speed Future.

5.2 Model Families and Output Scope

5.3 Overall Request Structure

POST /v1/videos
{
  "model": "<YOUR_MODEL_ALIAS>",
  "prompt": "Describe the video you want",
  "user": "optional-user-id",
  "seed": 123456,
  "metadata": {
    "duration": 4,
    "resolution": "720p",
    "ratio": "adaptive",
    "generate_audio": false,
    "content": []
  }
}

5.4 Top-Level Fields

5.5 metadata Fields

Metadata is the control plane

Engineers should avoid putting duration, resolution, ratio, and generate_audio at the top level. Put Seedance-specific controls under metadata instead.

5.6 metadata.content Item Structure and Roles

metadata.content is an ordered array. Each item requires type (media format) and role (purpose). Supported roles are reference_image, reference_video, reference_audio, first_frame, and last_frame. Use image_url for image/frame roles, video_url for reference_video, and audio_url for reference_audio. Item order is preserved for @Image1, @Video1, and @Audio1.

reference_image item:
{ "type": "image_url", "role": "reference_image",
 "image_url": { "url": "https://example.com/image-1.jpg" } }

reference_video item:
{ "type": "video_url", "role": "reference_video",
 "video_url": { "url": "https://example.com/video-1.mp4" } }

reference_audio item:
{ "type": "audio_url", "role": "reference_audio",
 "audio_url": { "url": "https://example.com/audio-1.mp3" } }

Reference video items use type=video_url with role=reference_video. Keep reference media accessible throughout processing; commercial terms are outside this technical guide.

5.7 Seedance 2.5 API Request Specification

Seedance 2.5 is available only when Light Speed Future provisions a tenant-facing alias. Use only the documented fields and combinations below.

Seedance 2.5 request specification | Use documented fields only. For Omni editing and extension, keep the explicit task type, prompt intent, reference assets, ratio, and duration mutually consistent.

Seedance 2.5 Explicit Omni Edit Example

POST /v1/videos
{
  "model": "<YOUR_SEEDANCE_2_5_MODEL_ALIAS>",
  "prompt": "Edit @Video1 using the visual details from @Image1 and the sound style from @Audio1.",
  "metadata": {
    "client_request_id": "video-job-20260824-edit-0001",
    "omni_reference_task_type": "edit",
    "duration": -1,
    "resolution": "1080p",
    "ratio": "adaptive",
    "output_format": "mov",
    "return_last_frame": true,
    "watermark": false,
    "generate_audio": false,
    "content": [
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://example.com/video-1.mp4"
        }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://example.com/image-1.jpg"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "https://example.com/audio-1.mp3"
        }
      }
    ]
  }
}

Use metadata.omni_reference_task_type only for Seedance 2.5 Omni reference-to-video requests. Omitting it uses auto behavior and lets the model infer the subtask. Explicit reference, edit, or extend validates known task constraints earlier, but the prompt and inputs must still match; otherwise the task can fail asynchronously with InvalidParameter.TaskTypeMismatch. Do not send a generic task_type field.

Seedance 2.5 Explicit Omni Extend Example

POST /v1/videos
{
  "model": "<YOUR_SEEDANCE_2_5_MODEL_ALIAS>",
  "prompt": "Continue @Video1 forward, preserving the scene and motion.",
  "metadata": {
    "client_request_id": "video-job-20260824-extend-0001",
    "omni_reference_task_type": "extend",
    "duration": 5,
    "resolution": "480p",
    "ratio": "adaptive",
    "generate_audio": false,
    "content": [
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://example.com/video-1.mp4"
        }
      }
    ]
  }
}

For edit, omit duration or set it to -1. For extend, omit duration or use -1 or an integer from 4 to 30. Both modes require at least one reference_video; omit ratio or set it to adaptive.

5.8 Common Video Generation Examples

Example A: Minimal text-to-video

POST /v1/videos
{
  "model": "<YOUR_MODEL_ALIAS>",
  "prompt": "A person speaking naturally to camera in a clean indoor setting.",
  "metadata": {
    "duration": 4,
    "resolution": "720p",
    "ratio": "adaptive",
    "generate_audio": false
  }
}

Example B: Seedance Mini text-to-video

POST /v1/videos
{
  "model": "<YOUR_MINI_VIDEO_MODEL_ALIAS>",
  "prompt": "A cinematic close-up of a premium skincare bottle on a clean white background, soft studio lighting, smooth camera movement.",
  "metadata": {
    "duration": 4,
    "resolution": "720p",
    "ratio": "adaptive",
    "generate_audio": false
  }
}

Example C: Single-image reference

POST /v1/videos
{
  "model": "<YOUR_MODEL_ALIAS>",
  "prompt": "Create a product video using Image 1 as the visual reference. Keep the product shape and label consistent.",
  "metadata": {
    "duration": 4,
    "resolution": "720p",
    "ratio": "adaptive",
    "generate_audio": false,
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product-reference.jpg"
        },
        "role": "reference_image"
      }
    ]
  }
}

Example D: Reference video input

POST /v1/videos
{
  "model": "<YOUR_MODEL_ALIAS>",
  "prompt": "Use the camera rhythm and motion style from Video 1, while creating a new product-focused short video.",
  "metadata": {
    "duration": 4,
    "resolution": "720p",
    "ratio": "adaptive",
    "generate_audio": false,
    "content": [
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/reference-camera-motion.mp4"
        },
        "role": "reference_video"
      }
    ]
  }
}

Example E: Standard 4K output when enabled

POST /v1/videos
{
  "model": "<YOUR_STANDARD_VIDEO_MODEL_ALIAS>",
  "prompt": "Generate a premium product commercial with slow cinematic camera movement and high-detail lighting.",
  "metadata": {
    "duration": 5,
    "resolution": "4k",
    "ratio": "16:9",
    "generate_audio": false
  }
}

5.9 Unsupported Resolution Behavior

POST /v1/videos
{
  "model": "<YOUR_MINI_VIDEO_MODEL_ALIAS>",
  "prompt": "A short product clip.",
  "metadata": {
    "duration": 4,
    "resolution": "1080p",
    "ratio": "adaptive",
    "generate_audio": false
  }
}

Expected result: the request is rejected with an invalid_request_error. No video task is created. The same applies to native Seedance 2.5 4k requests and Fast or Mini 1080p/4k requests under the current package rules.

5.10 Retrieve Task Status

GET /v1/videos/{task_id}
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "<YOUR_MODEL_ALIAS>",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "https://example.com/generated-video.mov",
    "last_frame_url": "https://example.com/generated-last-frame.jpg"
  },
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  }
}

Poll the same GET /v1/videos/{task_id} every 30 seconds or longer. If a connection is interrupted, resume polling the same task ID; do not submit another POST only because polling was interrupted. Stop when status is completed, failed, or expired. Video callbacks are not supported.

Seedance 2.5 Error Details

When a task reaches failed or expired, check the error object returned by GET /v1/videos/{task_id}:

{
  "status": "failed",
  "error": {
    "code": "InvalidParameter.TaskTypeMismatch",
    "message": "The task type identified by the model does not match the specified value."
  }
}

Use error.code for application logic and error.message for diagnostics. If a specific error code is unavailable, the API returns video_generation_failed.

5.11 Idempotency

Use metadata.client_request_id and retain the public task ID. Follow section 4 for identical-request replay, interrupted polling and unknown submission outcomes.