How Do I Format reference_audio_urls in the Request?
In today's rapidly evolving creative tech landscape, APIs that merge multiple media modalities into one seamless request are game-changers. Companies like Apiframe are leading the charge by offering a single endpoint to generate videos from text, images, and audio references, providing unparalleled flexibility for creators and developers alike. If you've engaged with platforms such as ByteDance and CapCut, you already know the value of powerful, integrated media tools that fit into modern creative workflows.
This post dives deep into one of Apiframe's standout features — the formatting and use of the reference_audio_urls parameter in requests to POST https://api.apiframe.ai/v2/videos/generate. We'll cover how to correctly format the audio reference URLs in an array, explain roles in multitasking with seedanceParams, and why native synchronized audio in the same generation pass matters for next-gen video storytelling.
Why reference_audio_urls Matter
Before diving into formatting, it's important to understand why reference_audio_urls are vital. https://bizzmarkblog.com/how-do-i-choose-916-vs-169-for-seedance-outputs/ When you generate videos that fuse text prompts and images with referenced audio, your final output becomes richer and more contextually aligned with the source sound. This feature is particularly useful for creative tasks like:
Generating video clips choreographed to specific background music or sound effects Matching lip sync or ambient soundscapes in character animations or ads Creating synchronized multimodal storytelling sequences, combining style, motion, and audio into a unified output
Apiframe's API approach natively supports these workflows by accepting an array of reference audio URLs so you can specify multiple audio references with clear roles in one API call.
One Endpoint to Rule Them All: Text-to-Video, Image-to-Video, Reference-to-Video
Many video generation services require different endpoints or separate processes to generate content based on text, images, or audio. Apiframe simplifies this by using a single endpoint:
POST https://api.apiframe.ai/v2/videos/generate
This endpoint supports multimodal inputs simultaneously. You can:
Send in text prompts to generate new video content Supply images as visual references to inform style or composition Include audio references via the reference_audio_urls parameter for sound guidance, all in one call
Because of this unified interface, you have total control and flexibility to create videos seamlessly combining diverse inputs —– no juggling multiple API calls or complex synchronization post-processing.
Understanding the reference_audio_urls Parameter
Crucially, reference_audio_urls must be passed as an array of URLs in your JSON payload. Each URL should point to an external audio asset stored in a publicly accessible location or a private one that your system can securely access.
The parameter format looks like this:
"reference_audio_urls": [ "url": "https://cdn.mysite.com/audio/background-music.mp3", "role": "sound" , "url": "https://cdn.mysite.com/audio/voiceover.wav", "role": "motion" ]
Let’s discuss these key aspects:
Array of audio references: Multiple inputs are possible. For example, a background score, a voice-over, or ambient sounds. Role annotation: Each URL can be tagged with a semantic role like style, motion, or sound. This helps the generation engine understand how to incorporate each audio reference in the final output.
Role Definitions and Their Impact
Role Description Effect in Generation style Defines the artistic audio style or genre (e.g., jazz, lo-fi beats) Influences the tone, rhythm, and mood of video elements and transitions motion Highlights audio cues tied to physical movement, such as footsteps or instrumental action Drives synchronized character animations or camera movements triggered by beats sound General ambient or background audio Creates an audio landscape that complements visuals but does not direct motion
By tagging each URL with a role, you help the API's seedanceParams engine choreograph how audio ties into visual motion and style fluidly — a capability reminiscent of director-style camera movement guidance via prompt language. This ensures the output is truly cohesive.
Sample Request Using reference_audio_urls
Here’s an example curl request demonstrating a properly formatted payload including the reference_audio_urls array:
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 bustling city street at sunset with vibrant neon lights", "reference_image_urls": ["https://cdn.mysite.com/images/cityscape.png"], "reference_audio_urls": [ "url": "https://cdn.mysite.com/audio/neon-beats.mp3", "role": "style" , "url": "https://cdn.mysite.com/audio/crowd-movement.mp3", "role": "motion" ], "seedanceParams": "cameraMovement": "smooth tracking shot circling around the street performers", "generate_audio": true , "resolution": "1920x1080", "output_format": "mp4" '
This single request harnesses text, image, and multiple audio streams with explicit role tagging. The seedanceParams field specifies high-level direction, including integrated audio and camera movement instructions, which Apiframe’s engine synthesizes in the same generation pass. This native synchronization cuts out manual audio/video alignment headaches typical on other platforms.
Checking Job Status with GET https://api.apiframe.ai/v2/jobs/id
Once you submit the generation job, Apiframe returns an ID. You query the status and results via:
GET https://api.apiframe.ai/v2/jobs/id
Where id is the job ID received in your POST response.
HTTP Status Meaning 200 OK Job completed successfully; download URLs provided in JSON response 202 Accepted Job is in progress 400 Bad Request Malformed request, e.g., invalid reference_audio_urls formatting 401 Unauthorized Invalid or missing API key 500 Internal Server Error Server-side error; retry after a delay
Always ensure you sanity-check your reference_audio_urls for accessibility and correct role tags. Improper URLs or role names can cause unexpected failures or degraded output quality.
Pricing Example
Apiframe’s billing model is straightforward and transparent: you are billed per second of video output. That means you only pay for the length of the generated video, regardless of how many media references (images, audio URLs, text scopes) you include in the input. This is quite efficient compared to some platforms that charge based on input complexity or iterations.
Why Choose Apiframe Over Other Options?
You might be familiar with ByteDance and CapCut, industry giants offering video editing and creative content tools. However, Apiframe distinguishes itself with:
An API-first design: Tailored specifically for developers seeking programmatic control over video generation pipelines Unified multi-input support: Combines text, images, and audio references in one go instead of separate tools or manual merges Advanced seedanceParams: Allowing director-style control — camera movement, audio sync, and visual style dictation via natural language prompts Native synchronized audio generation: Audio is embedded as part of the generation pass, no post-processing required
For creators and developers building interactive, immersive content or ad-tech solutions, these features dramatically simplify seedanceParams workflows and reduce latency.
Best Practices and Final Tips
Validate your URLs: Make sure the audio URLs are accessible publicly, or your authentication headers/tokens are correctly configured if private. Use correct role names: Stick to documented roles such as style, motion, and sound. Avoid generic or misspelled role tags. Sanity-check parameters: Always verify that your resolution, audio generation flag (generate_audio), and other seedanceParams have sensible defaults or explicit values to avoid unexpected behavior. Test a minimal working request: Start with one well-formed audio URL and expand after confirming the API response status is 202 or 200 before scaling complexity.
Summary
Formatting reference_audio_urls correctly as an array of URLs with defined roles is a fundamental step in leveraging Apiframe’s powerful video generation API. The unified endpoint model simplifies integration by supporting text-to-video, image-to-video, and reference-to-video workflows seamlessly. Roles like style, motion, and sound in your audio references unlock director-level control over camera movement and multimodal synchronization, all baked into the same generation pass.
With transparent pricing based on generated seconds, and tooling to check job status via a GET endpoint, Apiframe provides a robust, developer-friendly environment to build immersive media experiences. If you’re building with the vision of offerings like ByteDance and CapCut but want API-first customization and extensibility, Apiframe is a compelling choice.
Try out the following sample curl to get started, and watch how your videos come alive with integrated, role-aware audio references!