AI generation API reference images: send a reachable URL and verify the adapter

A reference image request contains a URL that the upstream generation service can retrieve. A path on your laptop, a browser-only blob URL, or a private application page is not a remotely downloadable image. Start by proving that the reference is reachable, then inspect how the selected adapter maps it into the upstream request.

1. Prepare an asset URL with the right lifetime

Upload the reference through your own approved storage workflow and obtain an HTTPS URL that returns image bytes without an interactive login. If you use a signed URL, its lifetime must cover the period in which the provider may fetch it, including possible queue delay. This repository does not publish a universal minimum signed URL lifetime, so choose and monitor a policy suitable for your workload.

Check the exact URL from an environment outside your logged-in browser session. A successful browser view may depend on cookies or a local network connection that the generation provider does not have. Avoid sharing a confidential signed URL in public logs or support screenshots.

2. Send one reference deliberately

The following Python helper constructs a Seedance request. It does not perform an HTTP request or create a generation until you pass its result to your submission client. Replace the example asset URL with one you control and have verified.

from urllib.parse import urlparse

def reference_video_payload(image_url: str, prompt: str) -> dict:
    parsed = urlparse(image_url)
    if parsed.scheme != "https" or not parsed.netloc:
        raise ValueError("Use a remotely reachable HTTPS image URL")
    if parsed.username or parsed.password:
        raise ValueError("Do not embed credentials in image URLs")
    prompt = prompt.strip()
    if not prompt:
        raise ValueError("Prompt is required")
    return {
        "model": "seedance-2.0-fast",
        "prompt": prompt,
        "duration_sec": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "image_inputs": [image_url],
    }

payload = reference_video_payload(
    "https://assets.example.com/references/boat.jpg",
    "The boat gently rocks while the camera slowly moves closer",
)

Submit this body to POST /api/v1/video/generations. For a Nano Banana image operation, use POST /api/v1/images/generations, change the model to nano-banana, remove video duration and resolution fields, and set the desired image count with n.

3. Understand the current array mapping

Both public routes accept the snake_case image_inputs field and map it to the adapter’s imageInputs. The current Seedance and Nano Banana adapter implementations read imageInputs[0] and forward it as image_url. Additional array entries do not become a multi-reference composition in these implementations.

This distinction matters when designing your upload UI. Showing several selected images can imply that all of them influence the generation. Limit the UI to one reference for these adapters or explicitly tell users which reference is active. Do not claim a multi-image fusion feature simply because the request field is an array.

4. Diagnose access separately from generation

Local URL parsing proves syntax, not accessibility or media validity. Check for login redirects, expired signatures, access restrictions, and responses that return HTML rather than image bytes. If your application fetches user-supplied URLs itself, add its own network destination controls; do not turn a validation helper into an unrestricted server-side URL fetcher.

After acceptance, preserve job_id and observe the same job. A provider fetch or generation failure can appear as a failed job with an error object, even when the status HTTP response is successful. Do not keep resubmitting to debug a URL you have not yet verified independently.

Common mistakes and verification

Avoid local filesystem paths, blob: URLs, and URLs copied from pages requiring your browser cookies. Do not assume a reference guarantees exact product identity, exact composition, or a particular motion outcome; inspect generated assets against your own quality requirements.

Verify the reference returns image content without a logged-in session, its access window covers queueing, and the payload contains the intended first URL. Test malformed URLs and extra reference selections locally. Confirm failed and pending fixtures do not attempt to display null outputs as a completed asset.

See image-to-video fundamentals, Seedance image guidance, and input validation for model and application details.

Continue with code and integration

• AI generation API Docker: inject secrets when the worker starts
• AI generation API env variables: configure local and deployed clients consistently
• AI generation API Express: validate requests before forwarding them
• Browse all code and integration guides

Models covered on this page

• Seedance 2.0
• Nano Banana