LightSpeedFuture

API REFERENCE

LSF Seedance2.5 Production

Production · availability by tenant

LSF Seedance2.5 Production is deployed. Use the exact Production alias and output combinations enabled for your tenant; native-generation or standalone-enhancement access does not automatically grant Production access.

Submit one request to create a finished video with Seedance 2.5 creative controls and your selected Production tier. Optionally request a JPG last frame from the final result. The customer receives one public task and one final charge.

7.1 Product selection and outputs

TierUse this aliasAllowed tier-specific fields
Lite<YOUR_PRODUCTION_LITE_MODEL_ALIAS>Common FPS and bitrate controls. No scene, enhance_style or bit_depth.
Standard<YOUR_PRODUCTION_STANDARD_MODEL_ALIAS>scene; enhance_style; common controls. No bit_depth.
Pro<YOUR_PRODUCTION_PRO_MODEL_ALIAS>enhance_style; Professional bit_depth; common controls. No scene.

Select Lite, Standard or Pro through model, not tool_version. Final named resolutions are 1080p, 2k and 4k when enabled. Final video format is MP4. Arbitrary resolution_limit, MOV, 6K and 8K are outside this Production contract.

7.2 Request fields

FieldRequiredProduction behavior
modelYesExact Production tier alias issued to your tenant.
promptConditionalRequired for text-only generation; optional with supported reference or frame content.
metadata.durationOptionalRequested output seconds: omitted, -1, or integer 4–30 subject to the inherited mode rules. Edit accepts omitted or -1. Actual delivered duration governs settlement.
metadata.resolutionYesRequired final enhanced target: 1080p, 2k or 4k. There is no default.
metadata.contentFor reference / frame inputOrdered image_url, video_url and audio_url items with the roles in section 5.6. Video references can use an accessible HTTPS URL or an authorized asset:// URI.
metadata.
omni_reference_task_type
Optionalauto, reference, edit or extend with the native Seedance 2.5 mode rules in section 5.7.
metadata.ratioOptionalText / reference: adaptive, 16:9, 4:3, 1:1, 3:4, 9:16, 21:9. Frame control, edit and extend: adaptive only.
metadata.generate_audioOptionalBoolean; set explicitly when the application requires a specific audio behavior.
metadata.watermarkOptionalBoolean watermark request.
metadata.fpsOptional15–120 target output FPS. Omit to preserve source FPS. No FPS price multiplier in the current Production pricing model.
metadata.bitrate_level / bitrateOptionallow / medium / high preset or integer 10–150000 kbps. Explicit bitrate wins when both are present.
metadata.sceneStandard onlycommon, ugc, short_series, aigc, old_film. Omission preserves common default behavior.
metadata.enhance_styleStandard / Pro onlyhd or natural.
metadata.bit_depthPro onlyInteger 8, 10, 12 or 16. The 16-bit provider-profile limitations remain unverified; see section 6.2.
metadata.return_last_frameOptionaltrue requests a JPG from the final enhanced video. Requires this capability to be available for your tenant. Omit or use false if not needed.
metadata.client_request_idStrongly recommendedBusiness request identifier, scoped to the API Token. Use the same Token, request ID and unchanged payload for an identical replay. The examples use short printable ASCII identifiers.

Keep output and generation controls inside metadata. Top-level mode is rejected. Do not send generic task_type, standalone metadata.video_url, customer-supplied duration measurements for input references, provider credentials, callbacks or routing fields. Video references belong in metadata.content.

The inherited reference limits are 30 images, 10 videos, 10 audio items and 50 total. Preserve item order for references such as @Image1, @Video1 and @Audio1. Editing requires a 4–30 second reference video; frame/edit/extend aspect ratio must remain adaptive.

7.3 Example A · Standard text to enhanced 1080p

POST /v1/videos
{
  "model": "<YOUR_PRODUCTION_STANDARD_MODEL_ALIAS>",
  "prompt": "A ceramic cup on a desk in soft daylight. The camera is still.",
  "metadata": {
    "duration": 5,
    "resolution": "1080p",
    "fps": 24,
    "scene": "common",
    "generate_audio": false,
    "return_last_frame": false,
    "client_request_id": "production-standard-001"
  }
}

A successfully accepted Production request returns HTTP 202. Save its public task identifier. Do not create a second enhancement request: the backend starts that stage automatically.

{
  "id": "<YOUR_TASK_ID>",
  "task_id": "<YOUR_TASK_ID>",
  "status": "queued"
}

This is a selected-field response illustration, not an exhaustive response schema. Query GET /v1/videos/{task_id} with the task-owning API key until the public task reaches a terminal state.

7.4 Example B · Lite 2K with an HTTPS video reference

POST /v1/videos
{
  "model": "<YOUR_PRODUCTION_LITE_MODEL_ALIAS>",
  "prompt": "Use @Video1 as a motion reference for a new product scene.",
  "metadata": {
    "duration": 5,
    "resolution": "2k",
    "fps": 60,
    "generate_audio": false,
    "content": [
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://example.com/reference-video.mp4"
        }
      }
    ],
    "return_last_frame": false,
    "client_request_id": "production-lite-reference-001"
  }
}

metadata.duration requests the output duration; it is not the input-video duration. LSF validates the input video and measures its duration before the initial reservation.

7.5 Video URLs, assets and measured input duration

Input formHow it is handled
HTTPS video URLLSF uses a bounded media read to validate duration before acceptance. Supply a direct, stable and accessible media URL. A link that plays in a browser can still fail this validation.
asset:// video referenceThe asset must be authorized for the tenant, have video type and Active status, and be accessible in the configured asset context. LSF obtains temporary asset access internally and measures duration.
Multiple video referencesInput seconds are accumulated across the submitted video inputs. Fractional seconds are preserved; do not round each reference up. Repeated video inputs can contribute repeatedly.
Image or audio referencesDo not add input-video seconds. A last-frame still image also remains a no-video-input request unless a video is included.
Accepted identical replayReuses the task’s frozen input-duration and pricing information. It does not re-measure accepted inputs or create a new paid job.
New requestRevalidates authorization and obtains fresh temporary asset access where required. Do not assume a previous URL or permission check remains valid indefinitely.

Provide URLs that remain accessible long enough for validation and processing. Private or loopback destinations, unsafe redirects and unsupported or unstable media access are rejected. Validation may require byte-range access; a server that cannot provide consistent media metadata may be unsuitable.

LSF’s measured input duration is the basis for this retail workflow. It is not a supplier-reported billed-input-seconds value. Customers do not submit a trusted Tin field or configure a media probe.

7.6 Example C · Pro 4K, asset video and enhanced last frame

POST /v1/videos
{
  "model": "<YOUR_PRODUCTION_PRO_MODEL_ALIAS>",
  "prompt": "Use @Video1 as a reference for smooth camera motion and lighting.",
  "metadata": {
    "duration": 5,
    "resolution": "4k",
    "fps": 24,
    "generate_audio": false,
    "content": [
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "asset://<YOUR_VIDEO_ASSET_ID>"
        }
      }
    ],
    "return_last_frame": true,
    "client_request_id": "production-pro-asset-001"
  }
}

Do not include scene in a Pro request. Use only an asset ID that is authorized and Active. Virtual and real-human asset creation and verification remain distinct workflows; a real-human asset does not bypass its verification requirements.

Last-frame behavior

  • return_last_frame=true is an output request. The JPG comes from the final delivered video.
  • An input content item with role=last_frame is a generation constraint. It does not request extraction of the delivered video’s last frame.
  • The requested outputs belong to the same public task. Do not submit a separate frame-extraction request or bill its internal stage as a second customer job.
  • Use the returned last-frame URL only when present on a successful result, and store it promptly if it is needed for subsequent work.
  • Reusing a frame in another request does not automatically create a documented parent/child work relationship or prove its original-media provenance. Maintain any application lineage in your own system.

7.7 Results and progress

GET observes the public workflow; it is not needed to trigger the next internal stage. Continue polling the original task through nonterminal states. A completed Production result is the final enhanced MP4 and, when requested and returned, the enhanced-result JPG.

Response itemClient handling
id / task_idStore the public task identifier returned at creation; use it for subsequent GET requests.
statusTreat completed, failed and expired as terminal. queued and in_progress are nonterminal. Do not create a new job solely because progress is slow.
metadata.urlFinal enhanced video URL. Read actual output duration / resolution / FPS where returned, and retain the response for reconciliation.
metadata.last_frame_urlOptional final-frame image URL. Absent optional fields are omitted, not filled with null. Do not assume this field exists when extraction was not requested or the task has not completed successfully.
errorOn failure, use the sanitized code/message when supplied. Do not depend on internal stage identifiers or raw provider messages.

Result URLs are temporary

Copy delivered video and image files into customer-controlled storage. The intermediate generation output is not the Production deliverable. A successful final video URL must not be replaced by an intermediate URL after a later error.

7.8 Pricing, reservation and reconciliation

Use the agreed tenant rate for the selected Production tier, resolution and input mode. The rate already reflects the tenant’s commercial terms. The current Production model does not apply an FPS multiplier.

Input modeChargeable durationFinal charge basis
No video inputFinal enhanced output duration rounded up to a whole secondAgreed no-video rate × rounded output seconds
Any video inputSum of measured input-video seconds + final enhanced output duration rounded up to a whole secondAgreed video-input rate × combined seconds

A still image, a first/last-frame image or an audio-only reference does not by itself activate video-input pricing. Reference video, editing, extension and mixed inputs containing video do. Use the video-input rate for the same tier and resolution, not a rate from another tier.

Worked duration examples — no price quotation

RequestCalculationChargeable seconds
No video input; final output 5.042 sceil(5.042)6
One 5.000 s input video; final output 5.017 s5.000 + ceil(5.017)11
Input videos 2.125 s and 3.000 s; final output 5.042 s2.125 + 3.000 + ceil(5.042)11.125
One still image only; final output 5.042 sceil(5.042), no video-input seconds6

At submission, LSF reserves an estimate using the requested / estimated output duration and validated video-input duration. If output duration is automatic, the estimate can be conservative. The final enhanced duration can exceed the requested value; the reservation is not a spending cap.

The accepted task freezes its applicable rate and input information. Terminal reconciliation settles the final amount once and refunds or collects the difference from the reservation as applicable. Repeated GET or an accepted identical replay does not create duplicate financial operations. Display rounding is not a substitute for the final balance or invoice record.

A Production job has one final customer charge, including the requested last-frame output. Failed tasks and uncertain outcomes must be reconciled against the original task; an unknown outcome is not proof that a refund is due or that no processing occurred.

7.9 Request rejection and safe recovery

ConditionWhat to do
Product or output combination not enabledConfirm the supplied alias and tenant availability with LSF.
Wrong tier fieldsRemove scene from Pro; remove scene, enhance_style and bit_depth from Lite; do not use tool_version to select a Production tier.
Unusable asset / URL / durationCorrect the source or authorization before creating an intentionally new request. Do not submit a manually asserted input duration to bypass validation.
Insufficient allowanceCheck GET /v1/billing/balance and leave room for final reconciliation.
Accepted task remains nonterminalKeep the original task and request ID; resume GET. Contact LSF with the public ID if progress remains uncertain.
Terminal failureInspect the error and any reservation adjustment. Start a new job only deliberately, after addressing the cause.

Search documentation

Search pages and headings. Use Tab or arrow keys to move through results.