From a Suno Track to a Hosted Music Video: Designing the Async Workflow

hao kang — Thu, 16 Jul 2026 12:28:03 +0000

A music generator such as Suno can give a creator a finished track. It does not automatically give them a finished music video.

The usual next step is a toolchain:

Export the song as an MP3.
Use an image model such as Nano Banana to establish the artist, character, location, or visual style.
Turn those references into individual video shots with a model such as Veo, Seedance, or another video generator.
Route performance close-ups through a lip-sync-capable step when the singer needs to match the vocals.
Prepare lyrics or an SRT file, then align captions with the song.
Retry failed shots, choose the usable takes, match aspect ratios, place the original track, and compose the final timeline.
Upload the exported MP4 somewhere the application can reliably deliver it.

Modern multimodal models reduce parts of this work, but an application still has to own the workflow around them. A full song is longer than one generated shot. Character consistency can drift. One failed scene should not require restarting everything. Subtitle timing, task state, retries, cost evidence, and final delivery still need product code.

I wanted to see what this integration would look like if the application only had to submit the source material and track one job. For the concrete implementation below, I used the BeatAPI Music Video API.

At the simplest level, the application provides:

one MP3, WAV, AAC, or M4A file;
one to seven reference images;
optional creative direction;
optional lip-sync and subtitle controls;
output format and quality settings.

The API returns a task ID immediately and delivers a hosted MP4 when the workflow succeeds. The default path does not require the developer to review or edit a storyboard.

Before:
song -> reference images -> generated shots -> lip sync
     -> subtitle timing -> retries -> editing -> hosting

Behind one workflow API:
audio + reference images + controls
-> one async task
-> hosted MP4

By the end of the tutorial, you will have a backend flow that:

uploads local source files;
creates one asynchronous music-video task;
polls without hammering the status endpoint;
uses webhooks without making them the only recovery mechanism;
stores the final hosted MP4 and support evidence.

Where the workflow boundary sits

This approach does not make image or video foundation models unnecessary. Those models still generate the underlying creative assets.

The difference is where the application boundary sits:

Manual workflow responsibility	BeatAPI contract
Upload and validate audio, images, and SRT files	`POST /v1/files`
Submit music, references, creative direction, lip-sync, subtitle, and format controls	`POST /v1/music-video/tasks`
Track many long-running generation steps	One durable task ID and explicit lifecycle states
Recover from missed events or process restarts	Task lookup plus webhooks
Assemble the result with the source track	Automatic music-video composition
Deliver the finished file	Hosted MP4 in `output.media`
Explain charges, failures, and refunds	Usage, error, status, and request evidence attached to the task

The application integrates with one stable workflow contract instead of coordinating every generation and delivery step itself.

Storyboard data and shot-level editing are optional advanced controls, not required steps in the default generation path. Teams that need more editorial control can inspect the returned shots, revise one scene, or recompose selected shots without rebuilding the entire video.

The minimum production architecture

A reliable integration has five layers:

Layer	Your application owns	API surface
Asset preparation	Validate and upload local audio, images, and subtitles	`POST /v1/files`
Task creation	Capture creative direction and output controls	`POST /v1/music-video/tasks`
State tracking	Persist queued, processing, success, and failure states	`GET /v1/tasks/{task_id}`
Completion events	Update backend records without keeping a request open	`/v1/webhooks`
Delivery	Store and render the final hosted MP4	`output.media[].url`

The important design decision is that your database record—not the browser tab and not an in-memory worker—is the durable owner of task state.

Step 1: prepare the inputs

The API cannot read /Users/me/song.mp3 or a private object URL from a browser. Inputs need public HTTPS URLs.

If your application starts with local uploads, send them through your backend and upload them with POST /v1/files. Save the returned URLs before creating the video task.

Useful preflight checks include:

Audio format: mp3, wav, aac, or m4a
Audio duration: 10–180 seconds
Audio size: 50 MB or less
Images: 1–7 public png, jpg, jpeg, or webp files
Image size: 50 MB or less per image
Prompt length: up to 3,000 characters
Optional subtitle input: a public .srt URL

Doing this validation in your UI produces faster feedback and avoids spending credits on requests that can never succeed.

Step 2: create the task

Keep the API key on your server:

export BEATAPI_API_KEY="sk_your_key"

Then create the music-video task:

curl https://api.beatapi.io/v1/music-video/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://media.example.com/song-preview.mp3",
    "images": [
      "https://media.example.com/artist-portrait.png"
    ],
    "prompt": "Create a vertical synth-pop performance video with neon reflections, close-up energy, and quick cuts during the chorus.",
    "language": "en",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "quality": "standard",
    "lip_sync": false,
    "add_subtitle": false,
    "compose_mode": "auto"
  }'

Persist the returned task ID immediately. A useful local record might contain:

type VideoJob = {
  userId: string
  beatapiTaskId: string
  workflow: 'music-video'
  status: string
  requestId?: string
  outputUrl?: string
  errorCode?: string
  errorMessage?: string
  creditsCharged?: number
}

That record gives your frontend and support tooling one stable place to read the job.

Step 3: poll without hammering the API

Video jobs do not benefit from one-second polling. Use a 5–10 second interval with jitter and stop when the task reaches a terminal state.

const terminalStates = new Set(['succeeded', 'failed', 'cancelled'])

const wait = (ms: number) =>
  new Promise((resolve) => setTimeout(resolve, ms))

async function waitForTask(taskId: string, apiKey: string) {
  for (let attempt = 0; attempt < 60; attempt += 1) {
    const response = await fetch(
      `https://api.beatapi.io/v1/tasks/${taskId}`,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
        },
      },
    )

    if (!response.ok) {
      throw new Error(`Task lookup failed: ${response.status}`)
    }

    const payload = await response.json()
    const task = payload.data

    if (terminalStates.has(task.status)) {
      return task
    }

    const jitter = Math.floor(Math.random() * 2_000)
    await wait(5_000 + jitter)
  }

  throw new Error('Task did not reach a terminal state in time')
}

In a real backend, add:

request timeouts;
retry limits for transient network failures;
cancellation support;
a maximum total wait time;
logging keyed by task ID and request ID.

Step 4: use webhooks, but keep polling as recovery

Webhooks are useful when a backend needs to react immediately:

update a database record;
notify a user;
trigger a downstream automation;
copy the final video into long-term storage.

They should not be your only source of truth. Delivery can fail even when generation succeeds. Keep GET /v1/tasks/{task_id} available for reconciliation jobs and user-triggered refreshes.

A practical model is:

webhook = fast update path
task endpoint = recovery and verification path
database = application-facing state

Step 5: store the final MP4 and support evidence

A successful task exposes media in output.media:

{
  "data": {
    "id": "task_8K2qA",
    "workflow": "music-video",
    "status": "succeeded",
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_8K2qA/0.mp4",
          "mime_type": "video/mp4"
        }
      ]
    },
    "usage": {
      "credits_charged": 150,
      "credits_refunded": 0
    },
    "request_id": "req_abc123"
  }
}

Store the hosted output URL with the task ID, request ID, status, and usage evidence. On failure, persist error_code and error_message as well.

Do not expose upstream provider job IDs or temporary provider URLs as your product contract. That couples your UI and support flow to infrastructure that may change.

Common mistakes

Mistake	Why it fails	Better approach
Sending a local file path	The remote API cannot access the user's machine	Upload first and pass the returned HTTPS URL
Holding one HTTP request open	Video generation is long-running and users disconnect	Return a task ID and process asynchronously
Polling every second	Adds load without improving completion time	Poll every 5–10 seconds with jitter
Trusting only the webhook	Delivery can fail or arrive late	Reconcile through the task endpoint
Keeping task state only in memory	Restarts lose the job	Persist task state in a database
Returning provider-specific URLs	URLs may expire and leak infrastructure details	Store the API's hosted MP4 output

Launch checklist

Before releasing the feature, verify:

[ ] API keys exist only on the server
[ ] Local inputs have an upload path
[ ] File type, size, duration, and image count are checked before task creation
[ ] Every request creates a durable database record
[ ] Polling uses bounded retries and jitter
[ ] Webhook events are verified before processing
[ ] A reconciliation path can query the task endpoint
[ ] The UI has explicit queued, processing, succeeded, and failed states
[ ] Support can inspect task ID, request ID, errors, usage, and refunds
[ ] The final MP4 URL is persisted after success

Try the request without writing the client first

If you want to inspect the request and response shape before adding it to an application, the same workflow is available in the public Postman workspace.

If you are implementing a long-running media API, which path do you normally document first: polling for the fastest first success, or webhooks for the production architecture?

Editorial disclosure: This is a first-party BeatAPI engineering article. It was prepared with AI assistance and reviewed by the product team against the public API contract before publication.

DEV Community: hao kang