In the ever-evolving world of AI-powered video generation, developers and creators demand flexibility and precision — whether it's turning text prompts into engaging clips, animating images, or remixing footage with creative direction. Companies like Apiframe, ByteDance, and CapCut have pioneered tooling that blends different input types seamlessly into one video generation pipeline.
One key to that success? The ability to specify an array of URLs for your reference_video_urls parameter in API requests. This post walks you through exactly how to format these references, how to use them with associated roles like style and motion, and what to expect from the seedanceParams that accompany these multimodal inputs. We’ll also highlight the Apiframe endpoints you’ll use to kick off and monitor your video jobs, including POST https://api.apiframe.ai/v2/videos/generate and GET https://api.apiframe.ai/v2/jobs/id.
One Endpoint for Everything: Text-to-Video, Image-to-Video, and Reference-to-Video
Unlike older fragmented tooling that required separate services or endpoints for different media types, platforms like Apiframe unify the entire creative pipeline. This means whether you are:
- Generating a video from a pure text prompt (“a soaring eagle in slow motion”), Animating an image asset with generative effects, or Remixing videos by referencing existing clips via URLs,
you use the POST https://api.apiframe.ai/v2/videos/generate endpoint and provide the appropriate request fields. The API intelligently determines your intended effect based on your parameters.
Why This Matters
This consolidated approach simplifies integration, reduces maintenance overhead, and mirrors the workflows of creative pros in companies like ByteDance and CapCut, where rapid iteration is key. You can embed text, images, and video references within a single job, letting you paint with all media types simultaneously.
Formatting reference_video_urls: The Basics
The parameter reference_video_urls accepts an array of fully-qualified URLs pointing to existing video assets you want to use as creative seeds or guides for your output. This is not just “one video” — you can pass multiple references to be interpreted with assigned roles.
Example in JSON:
"reference_video_urls": [ "https://cdn.example.com/videos/clip-style.mp4", "https://cdn.example.com/videos/clip-motion.mp4", "https://cdn.example.com/videos/clip-sound.mp3" ], ...Note: Always sanity-check your URLs for accessibility (public or valid CDN with authenticated access if needed) and preferably use HTTPS for security.
Setting Roles for Each Reference
Not all clips are created equal in how they influence your generated video. To control their interpretative function, the API supports assigning roles per reference video. Common roles include:
- style: Guides the visual style — color palette, art direction. motion: Provides movement cues or camera trajectories. sound: Directs the audio or soundtrack synthesis.
Here is how a fully formed reference section with roles looks in the body of your JSON request:
"reference_video_urls": [ "url": "https://cdn.example.com/videos/night-city-style.mp4", "role": "style" , "url": "https://cdn.example.com/videos/camera-pan-motion.mp4", "role": "motion" , "url": "https://cdn.example.com/videos/ambient-sound.mp3", "role": "sound" ], ...Understanding seedanceParams: The Director’s Toolbox
The magic of Apiframe’s API is not just in accepting multiple references but in how it blends them during generation. The seedanceParams (an evolving parameter set) governs how your input sources are mixed, weighted, and interpreted.
Here are some of the key parameters you can tune within seedanceParams:
Parameter Description Example Values Notes style_weight How strongly the style reference influences output 0.0 to 1.0 Default 0.7 recommended for visible style transfer motion_weight Controls adherence to motion cues 0.0 to 1.0 Higher values mimic camera movement closely audio_sync Enable native synchronized audio generation in same pass true / false Defaults to true; ensures lip-sync and sound effects aligned resolution Output video resolution e.g., "1920x1080" Sanity-check your default (avoid too low or ultra-high initially)For example, your request body might include:
"reference_video_urls": [ "url": "https://cdn.example.com/clip-style.mp4", "role": "style" , "url": "https://cdn.example.com/clip-motion.mp4", "role": "motion" ], "seedanceParams": "style_weight": 0.8, "motion_weight": 0.6, "audio_sync": true, "resolution": "1280x720" , "text_prompt": "a slow zoom over futuristic city skyline at dusk"Native Synchronized Audio: No Separate Pass Needed
Unlike many video generation tools that require you to generate visuals and audio separately and then stitch them together, Apiframe’s pipeline supports native synchronous audio generation. This means you specify your reference_video_urls including audio references (soundtracks, voice direction), set audio_sync: true, and your output will contain perfectly aligned audio and visuals in one go.
This is a crucial feature used by platforms like CapCut, where fast iterative video rendering with synced audio is a must.
Director-Style Camera Movement via Natural Language Prompting
One of the most exciting advances you can harness involves writing natural language prompts that command director-style camera movements. Combined with your motion reference clip, the API understands instructions such as:
- "a slow dolly zoom in on the subject" "a rapid pan left to right to reveal the cityscape" "a smooth crane shot moving upward into the sky"
By pairing these with your reference_video_urls containing movement cues, your videos achieve cinematic dynamism without manual keyframing.
ByteDance have famously incorporated such AI-driven natural language director cues into apps where creators request camera moves simply by typing, drastically lowering video production barriers.
Practical Example: Complete curl Request
To make this concrete, here’s a fully working curl command to generate a video using multiple reference URLs with roles and seedanceParams configured.
curl -X POST https://api.apiframe.ai/v2/videos/generate \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d ' "text_prompt": "a tranquil forest glade with gentle sunbeams", "reference_video_urls": [ "url": "https://cdn.contoso.com/videos/forest-style.mp4", "role": "style" , "url": "https://cdn.contoso.com/videos/forest-motion.mp4", "role": "motion" , "url": "https://cdn.contoso.com/audio/birds-chirping.mp3", "role": "sound" ], "seedanceParams": "style_weight": 0.75, "motion_weight": 0.5, "audio_sync": true, "resolution": "1920x1080" 'Once posted, you receive a jobId. Poll your job status using:
GET https://api.apiframe.ai/v2/jobs/jobIdThis endpoint will provide progress, estimated completion times, and the final generated asset URLs.
Pricing: Billed Per Second of Video Output
To manage expectations and budgets, Apiframe bills based on the length of the final video output — that apiframe.ai is, per second of video generated. This billing model encourages reasonable duration requests and lets you tailor your creativity to cost constraints.
Pro tip: Be explicit about output length in your prompt or additional parameters to avoid surprises.
Summary and Best Practices
Always format reference_video_urls as an array of objects with url and role keys to maximize control. Use natural language prompts enhanced by your motion and style clips for cinematic, director-grade outputs. Leverage seedanceParams to fine-tune blending weights and enable synchronous audio. Check your URLs for accessibility and HTTPS to avoid generation failures. Remember that billing is per second of output video, so keep your desired output length in mind.Whether you’re working in ad-tech, creator tools, or multimedia storytelling apps, adopting this multimodal, unified approach simplifies your integration and unlocks professional-grade video outputs. The interplay of the reference_video_urls array, its roles, and seedanceParams lets you wield powerful AI-driven direction changes and synchronized audio, just like teams at Apiframe, ByteDance, and CapCut.
Happy video creating!