Back to Blog

Seedance 2.5 API: How Do You Reuse the Last Frame?

Tutorials and Guides9764
Seedance 2.5 API: How Do You Reuse the Last Frame?

A product turns toward the camera. The first generated clip looks usable. In the next clip, the product changes color, the camera jumps, or a hand appears from the wrong side. Both API requests succeeded, yet the sequence still needs work.

For developers building with the Seedance API, the useful question is how to carry a selected visual state into the next request. BytePlus documents return_last_frame for obtaining the final image of a generated video. That image can then serve as the next task’s first-frame input. It gives the application an explicit visual handoff; it does not guarantee a seamless film.

This workshop follows a fictional product demonstration through that handoff. The goal is a small sequence your team can inspect and reproduce, using a local Python client and a supported hosted video-model route. It does not describe running Seedance model weights on your computer.

The local Seedance API workflow covers the initial client setup. Here we start later: the first generation exists, and you need to decide whether its final frame is suitable for another paid task.

Define what the second shot should inherit

Before touching the API, write a short continuity note. For a fictional blue desk lamp, the note might specify the lamp’s shape, the camera’s side of the table, the direction of its movement, and the position of the power cord. These details make the next result reviewable.

Separate what must remain stable from what should change. The next shot may require the lamp to rotate farther while its color, base, and table remain consistent. If the prompt simultaneously asks for a different room, a close-up, new lighting, and a new action, you have changed several conditions at once.

A single frame contains appearance and position at one moment. It does not contain the full preceding motion, dialogue timing, or every detail hidden outside the image. When the next clip needs that temporal information, consider the model’s documented video-reference or extension workflow as a separate option.

The Seedance 2.5 guide describes the supported generation modes. Choose a mode that matches the task rather than treating every reference as interchangeable. This article’s implementation uses an image handoff between distinct tasks.

For a broader creative pipeline, the Astra and Seedance production discussion provides context for separating writing and generation stages. In this smaller workflow, the handoff note should remain human-readable and specific enough for an editor to approve.

Request the final frame before generating the first clip

For the documented BytePlus task interface, request the final frame when creating the first video task. The task-creation reference describes return_last_frame as a boolean whose default is false.

This is a request fragment, not a complete call:

json
{
  "return_last_frame": true
}

Keep that fragment with the model identifier, task ID, original prompt, and other accepted settings. When you later inspect the result, you should be able to establish whether a final frame was actually requested. A missing image is easier to diagnose when the submitted payload is available.

The task-retrieval reference describes the returned content.last_frame_url. It also documents temporary output URLs. Save required assets promptly instead of treating a delivery URL as permanent storage.

When using an AI API relay, verify the creation and retrieval contracts separately. A route may expose a different task identifier, response wrapper, or parameter name. Passing a field in your request does not establish that the upstream service received it. Confirm the behavior with one small, documented task before building a sequence.

Keep this distinction visible in the interface you build for users. “Task completed” and “final frame available” are different states. If the latter is missing, the application should not silently choose an unrelated image from the project folder.

Approve the actual frame that will become the next input

Do not automatically feed the newest completed clip into the next task. Completion is a technical state; suitability is a production decision. A final frame may contain motion blur, a distorted product, or an accidental obstruction even when the earlier part of the clip looks good.

Review the end of the clip and the returned image together. Check the object identity, camera placement, lighting direction, readable product details, and whether the final pose can plausibly begin the next action. An attractive thumbnail alone does not establish that the transition works.

Record approval against the actual downloaded image bytes and the parent task identifier. If someone later replaces the file under the same name, the application should detect that change. A content hash is useful for this local consistency check, although it cannot prove where the image originally came from.

Use a controlled download process that records the relationship between the task response and the saved file. Then generate an approval manifest in your own review system. The manifest should identify the reviewer or decision record in production; the simplified code below only checks the decision and source relationship.

If the result fails technical playback checks, use the separate Seedance output validation guide. A bad handoff frame and a corrupted video download are different failures, and regenerating the next shot will not diagnose either one.

Build the continuation request from the approved asset

The following helper consumes a saved task response, a downloaded JPEG, and an approval manifest. It produces a BytePlus-style task body using the approved image as first_frame. It does not download assets, approve an image, or submit a paid task.

Install Pillow in your project environment. Save the code as build_seedance_continuation.py. The approval JSON must contain parent_task_id, frame_sha256, and decision, with the decision set to approved only after review.

python
import base64
import hashlib
import io
import json
import os
import sys
from pathlib import Path

from PIL import Image


def build_continuation(parent, frame_bytes, approval, model, prompt):
    if parent.get("status") != "succeeded" or not parent.get("id"):
        raise ValueError(
            "A successful parent task with an ID is required"
        )

    if not parent.get("content", {}).get("last_frame_url"):
        raise ValueError("Parent task does not identify a last frame")

    if approval.get("parent_task_id") != parent["id"]:
        raise ValueError("Approval belongs to another task")

    if approval.get("decision") != "approved":
        raise ValueError("Frame has not been approved")

    digest = hashlib.sha256(frame_bytes).hexdigest()

    if digest != approval.get("frame_sha256"):
        raise ValueError("Image bytes differ from the approved frame")

    # Conservative local demo limits, not model service limits.
    if not 0 < len(frame_bytes) <= 5_000_000:
        raise ValueError("Frame exceeds the demo byte policy")

    with Image.open(io.BytesIO(frame_bytes)) as image:
        if image.format != "JPEG":
            raise ValueError(
                "This handoff expects the returned JPEG"
            )

        width, height = image.size

        if width * height > 16_000_000:
            raise ValueError("Frame exceeds the demo pixel policy")

        image.verify()

    with Image.open(io.BytesIO(frame_bytes)) as image:
        image.load()

    if not isinstance(model, str) or not model.strip():
        raise ValueError("Supply a confirmed model identifier")

    if not isinstance(prompt, str) or not prompt.strip():
        raise ValueError("Supply a continuation prompt")

    uri = (
        "data:image/jpeg;base64,"
        + base64.b64encode(frame_bytes).decode("ascii")
    )

    body = {
        "model": model,
        "content": [
            {
                "type": "text",
                "text": prompt,
            },
            {
                "type": "image_url",
                "image_url": {"url": uri},
                "role": "first_frame",
            },
        ],
        "return_last_frame": True,
    }

    manifest = {
        "parent_task_id": parent["id"],
        "approved_frame_sha256": digest,
        "frame_dimensions": [width, height],
        "model_target": model,
    }

    return body, manifest


if __name__ == "__main__":
    parent = json.loads(
        Path(sys.argv[1]).read_text(encoding="utf-8")
    )
    frame = Path(sys.argv[2]).read_bytes()
    approval = json.loads(
        Path(sys.argv[3]).read_text(encoding="utf-8")
    )
    prompt = Path(sys.argv[4]).read_text(encoding="utf-8")

    body, manifest = build_continuation(
        parent,
        frame,
        approval,
        os.environ["SEEDANCE_MODEL_ID"],
        prompt,
    )

    Path("next-task.json").write_text(
        json.dumps(body, indent=2),
        encoding="utf-8",
    )

    Path("handoff.json").write_text(
        json.dumps(manifest, indent=2),
        encoding="utf-8",
    )

    print("Request prepared. No generation submitted.")

Run it after setting SEEDANCE_MODEL_ID to the exact model identifier supported by your account and chosen route:

bash
python build_seedance_continuation.py parent-task.json last-frame.jpg approval.json next-shot.txt

The helper intentionally requires an external approval record. It does not set approval to true simply because the image opens. Pillow’s image documentation explains image inspection and loading; Python’s hashlib reference documents the hash function used for the byte-level check.

This code checks consistency with a supplied manifest, not the authenticity of that manifest. In production, obtain it from a trusted review service and restrict who can create or modify it. Likewise, a matching task ID does not independently establish that the bytes were downloaded from that task’s URL; the controlled download record supplies that provenance.

The payload assumes that the selected route accepts a JPEG data URI in the documented image field. Check current input requirements before sending it. The Seedance image transport guide covers local paths, URL references, and Base64 inputs. Do not substitute a browser-only blob URL for the image bytes.

Write the next action around the supplied frame

Describe the next action relative to the approved image. For the fictional lamp, a suitable test direction is: maintain the blue lamp and table arrangement, continue its slow rotation in the same direction, and keep the camera on the same side. Ask for one action before attempting a complicated sequence.

Do not describe a new opening image that conflicts with the supplied frame. If the frame shows the lamp on the left and the prompt says it starts on the right, the model receives competing instructions. Resolve the production decision before asking the model to solve the contradiction.

Specify duration, resolution, and audio settings through the current documented configuration for the chosen model. The request builder above deliberately leaves those settings to your integration. It is not a promise that every Seedance route accepts the same options or uses the same defaults.

Keep the continuation prompt as a separate file alongside the handoff manifest. When the result drifts, you can distinguish a different prompt, a different approved frame, and a different model route. Without those records, repeated experiments quickly become impossible to compare.

Also decide whether the cut should preserve motion or simply preserve appearance. A matching lamp on the same table may be sufficient for a product montage. A continuous camera move is a stricter requirement. Write the intended transition down so the reviewer does not apply a different standard after seeing the result.

Recover assets before paying to regenerate them

An expired URL is an asset-delivery problem before it is a generation problem. If the approved JPEG is already stored correctly, your application can prepare a supported image input from those retained bytes. It does not need to regenerate the parent clip merely to recreate a download link.

If no valid image was saved, retrieve the existing task record where supported and investigate whether the output remains available. The task-list reference can help reconcile recorded jobs with provider-side tasks. Do not assume listing a task renews an expired output URL.

If the approved asset cannot be recovered, mark the continuation as blocked. A newly generated parent clip creates a new visual state and requires a new review. Reusing the previous approval against different bytes would hide a material change in the production sequence.

The same reasoning applies when a submit request times out. Before creating another child task, reconcile the original attempt using the route’s documented recovery behavior. The local manifest helps identify the intended handoff, but it is not a provider idempotency key and cannot prevent duplicate billing by itself.

Judge the transition as a sequence

Watch the transition at normal speed, then inspect the last moments of the first clip and the opening of the second. Look for identity changes, camera displacement, direction reversals, unexpected cuts, and visible lighting discontinuities. Review audio separately; a still image does not carry a continuous soundtrack.

Record failures in terms an operator can act on. “Wrong approved frame” points to asset selection. “Correct frame but inconsistent motion” points to the generated continuation or prompt. “Second task never created” points to submission. Those distinctions keep creative iteration separate from integration repair.

Begin with two clips. A ten-clip chain can amplify a defect introduced at the second handoff, making later generation expenditure less useful. Approve each boundary before expanding the sequence. This is a proposed production policy, not a guarantee about Seedance’s measured continuity performance.

For a 4SAPI pilot, confirm support for the required Seedance task route, final-frame output, and first-frame input. Prepare one approved handoff and one continuation request. The API gateway evaluation guide provides broader buying context; this pilot should be judged on whether your team can complete and review that specific sequence.

FAQ

Does this run Seedance locally?

The code and retained assets are local. Generation still occurs through the hosted API you select.

Does reusing the last frame guarantee continuity?

No. It supplies a visual starting condition. Motion, identity, lighting, and audio still require review.

Can the script approve a frame automatically?

It only checks an existing approval record and file consistency. Creative approval happens outside this helper.

Can I chain clips indefinitely?

Treat each boundary as a new generation decision with its own quality and cost. The two-clip test establishes a workflow, not an unlimited-duration guarantee.

Tags:Seedance 2.5 last_frame_urlSeedance consecutive videos PythonSeedance first frame continuation API

Recommended reading

Explore more frontier insights and industry know-how.