DEV Community: Eric Kang

Most "Vibe Marketing" Is Still Just One Prompt at a Time

Eric Kang — Wed, 16 Sep 2026 10:29:21 +0000

Vibe coding changed who could build software: the agent handles more syntax, while the human stays on intent and judgment. "Vibe marketing" should mean the same shift. But most examples are still one prompt for a post, another for a thread, another for a landing page — each starting from zero context.

That's not a marketing system. It's faster typing.

Shann Holmberg's (@shannholmberg) essay "How to Become a Marketing Engineer" is the clearest description I've read of what the real version requires: a functional workspace, tools and data connected before writing, a knowledge layer the agent can cite, and a human review gate. Our 3-person team had already built rough versions of those pieces for BeatAPI, but without a shared vocabulary. His structure helped us see the system.

A workspace organized by function, not by post

Don't hand an agent one big folder of "marketing stuff." Split it by function — content, SEO, paid, lifecycle — with separate workflows and outputs, plus one shared layer every function reads first: audience, product and positioning.

We'd converged on something close: one canonical positioning file, one growth playbook for channel status, and one rule of our own — one fact base, several channel-native drafts, never copy-paste. The same verified developer story became an X Article, a LinkedIn post, a Substack issue, a DEV Community piece, and localized Qiita and Zenn versions. The facts stayed fixed; the framing and technical depth changed with the audience.

Connect tools and data before you connect a writer

API access — to social data, generation tools and performance data — is infrastructure the agent needs before it can do useful work. That is also the premise behind BeatAPI, so it became a useful check on our own workflow: does the marketing agent have real access, or is it still guessing?

Last week we pointed an Agent at BeatAPI's Social Data API — one bearer key, one endpoint, the twitter.web.fetch_search_timeline action — and asked what AI topics were getting attention on X during a specific 24-hour window. Three searches returned 60 posts; after deduplication, 21 fit the window and grouped into five themes. The point isn't the number. The product we sell to developers is what our own marketing agent used to stop guessing.

A knowledge layer worth citing, not just reading

The essay's internal/external knowledge split is the right shape. We added one constraint: every claim needs a traceable source, not just a folder location.

This week we ran one research brief through four independent AI research passes — not six, even though we started with six files. Two pairs were a report and its operating workbook, not separate studies. Across the four real passes we collected roughly 160 raw candidate pain points, mapped them into 25 recurring problem families, and excluded five that were not actually user pain. We kept each original source instead of replacing the evidence with 25 clean summaries. An agent that can trace a claim back to the complaint can judge whether it is strong enough to publish. One that sees only the summary cannot.

Gates matter more as the agent does more

Permission boundaries stop being optional once an agent does real work. In our system, research can run without permission to publish, and a reviewed draft is still not an approved draft. We only mark an item published after the live public URL has been verified and recorded; the script then rejects missing URLs, malformed status links and the wrong account handle. More autonomy upstream is safe only because the downstream gate is stricter.

Where BeatAPI fits

If vibe coding needs a model, a harness and a workspace, real vibe marketing needs the same — plus specialist capabilities reached through APIs instead of a chat window. For us, BeatAPI supplies two concrete pieces: model APIs for image, video and text work, where long-running media and workflow calls use asynchronous tasks, polling or webhooks, hosted outputs and usage records; and the Social Data API for authenticated calls against a public action catalog. They share one account and key, but not every workload has the same execution shape.

Start with one function, one real API connection and one gate. If that task needs a model or live social data, run it against BeatAPI and inspect the result, cost and source trail before deciding what connects next.

BeatAPI is the capability layer for general-purpose agents

Eric Kang — Mon, 14 Sep 2026 16:10:39 +0000

A useful agent rarely depends on only one model.

It might use a text model to plan, an image model to create assets, a video model to produce an output, and external data to understand what's happening on a social platform. Later, it may need tools that can take actions in other products.

Every one of those capabilities usually means another provider, another account, another balance, another API key, and another integration to maintain. That's the problem BeatAPI solves.

What BeatAPI is

BeatAPI is a professional capability layer for general-purpose agents — one account, one key, growing access to the specialist capabilities an agent needs once a real task moves beyond conversation.

The product direction has three layers:

Models provide intelligence and generation — text, image, video, and workflow models.
Data gives an agent access to information outside its own context.
Tools will let an agent complete more actions in external systems.

We're not building another chat interface or another agent framework. The agents already exist. We provide the specialist capabilities those agents need.

Where we are today

Models are the current commercial foundation: developers get leading text, image, video, and workflow models at lower prices on matched public specifications, from one place, without integrating every provider separately.

Price gets people to compare providers, but price alone isn't enough — if a cheaper request produces worse output or more retries, it isn't actually cheaper. That discipline shapes how we price and route every model.

Data is the first expansion beyond models. BeatAPI now ships a Social Data API: one BeatAPI key, a public action catalog and MCP tool manifest covering platforms like TikTok, YouTube, Instagram, X, Reddit, and LinkedIn. It's the first concrete step from Models toward Data — not the end state.

Tools are the direction we're building toward, not something shipped yet.

Who this is for

BeatAPI serves two kinds of builders.

Developers and indie teams building or operating an agent directly — they need models and data without managing a separate account and integration for each capability.

SaaS and product platforms whose own users increasingly work through agents — these platforms need a single backend that gives their product's agents access to the same growing set of capabilities, instead of building and maintaining that integration layer themselves.

Both groups hit the same wall: every new capability is another vendor to evaluate, another key to manage, another bill to reconcile.

The direction

Models → Data → Tools is not a pipeline every task walks through in order. It's the set of capabilities a real task might need at once, unified behind one entry point.

Models are the current foundation. Social Data is the first expansion. The broader toolkit — more data sources, and tools an agent can act through — is the direction, not a finished product.

We're a three-person team, so we're deliberately entering through a focused, paid problem instead of shipping the entire vision at once.

BeatAPI: https://beatapi.io

I'd be interested in hearing from other builders: when you build an agent-powered product, which part creates the most operational friction — model access, external data, or connecting the agent to tools that can take action?

AI Can Write Anything. It Just Can't Tell You What's Worth Writing

Eric Kang — Sun, 13 Sep 2026 13:38:29 +0000

AI can turn a prompt into a clean draft in seconds. The harder question comes before the prompt.

What is worth writing about right now?

A model can suggest ten plausible topics. That does not mean anyone is discussing them, searching for them, or paying attention to them today. Without current information, the model is still guessing from what it already knows.

So we gave an Agent a real research task instead.

Find the AI topics attracting attention on X during the previous 24 hours, then produce a concise, evidence-based trend brief. Use BeatAPI Social Data as the source of live social data.

1. Give the Agent a question with boundaries

“What is trending in AI?” is too vague to produce a trustworthy answer. We defined an exact UTC window, limited the source to X, and used three simple query slices: AI, AI agent, and AI model.

The Agent inspected the available BeatAPI Social Data catalog and selected twitter.web.fetch_search_timeline. It called the action once for each query and received 60 posts in total.

That was the collection step. It was not yet a trend brief.

2. Turn returned posts into a usable sample

The Agent removed one duplicate, leaving 59 unique posts. It then checked the timestamps against the requested window and kept the 21 posts published during those 24 hours.

It ranked that sample using views as the primary signal and engagement metrics as supporting evidence. Finally, it grouped related posts into five themes and wrote a short explanation of what appeared to be driving attention around each one.

The numbers matter because they make the process inspectable:

60 posts returned
59 after deduplication
21 inside the exact 24-hour window
five themes in the final brief

This is a sample produced from three broad searches, not a definitive ranking of everything happening on X. A different query set would produce a different view of the day. The point is that the Agent can show how it reached the brief instead of presenting a confident answer with no visible trail.

3. Live data changes what the Agent can do

The writing model was never the main constraint in this task. The missing piece was access to current, task-specific data.

Once the Agent had that access, it could collect posts, compare timestamps, remove duplication, rank evidence, and turn the result into something a person could actually use.

The same brief could inform a research note, a content angle, or an article draft, but those are later decisions. The first useful output is a clearer picture of what people are responding to now.

This is where BeatAPI fits into the workflow. A general Agent handles the task, reasoning, and orchestration. BeatAPI supplies the specialist capability it needs at that moment. Social Data is one such capability alongside the models and workflows already available through BeatAPI.

The user should not have to leave the Agent, find another data vendor, create a separate account, study a new API, and maintain another integration every time the task needs a new kind of information.

4. The human still decides what is worth publishing

Live data does not remove judgment. It gives judgment better material.

Someone still needs to decide whether the queries were broad enough, whether a high-view post is relevant, whether several posts describe the same event, and whether the final angle adds anything useful.

The Agent can compress the research process. It cannot make every editorial decision on the user's behalf.

That is the workflow we want to keep improving:

Define the question → collect current data → filter and rank the evidence → build the brief → make the editorial decision

AI can already write almost anything. Give it access to what is happening now, and it has a much better chance of helping you decide what is worth writing.

If you are building with Agents, try one real task with a clear time window. Let the Agent call one BeatAPI Social Data action, then inspect the sources, result, and usage before deciding what happens next.

How We Built a Growth System Around an AI API—Before Finding Product-Market Fit

Eric Kang — Fri, 11 Sep 2026 17:16:03 +0000

In 10 days, BeatAPI reached 400+ signups and about $150 in revenue.

For our three-person team, the numbers were encouraging—but the more useful lesson was what happened behind them. AI has made software easier to build. It has not made distribution easy.

I am a developer, and I currently handle most of our growth. We are building BeatAPI: the professional capability layer for general agents, or, more simply, an “OpenRouter for Agents.” It gives agents one place to access AI models, Social Data, and MCP tools.

At first, I made a list of channels: SEO, X, developer communities, open source, directories, influencers, and UGC. The list kept growing, but it did not tell us what to do next.

The useful change was to stop treating channels as a checklist and give each one a job.

1. Search captures existing demand

We start with questions developers already ask: Which API fits this workflow? How much will the same model and specification cost? How should an agent handle a long-running task?

That leads to competitor pages for switching intent, free tools such as an API cost calculator for concrete decisions, and technical pages that answer one production question with verifiable evidence.

AEO adds a second feedback loop. More developers now begin with an AI assistant, so we ask the same questions from the user’s point of view and inspect the observable research path: which searches the assistant runs, which pages it opens, what it cites, and what evidence is missing.

If the answer lacks a matched comparison, we build one. If it needs structured data, we create a table or calculator. If the assistant relies on documentation, GitHub, or developer communities, we make sure our evidence exists there—not only on our own blog.

Ask like a user → inspect the sources → find the missing evidence → rebuild the content → distribute it where AI research happens

Our research workflow is itself agentic. Firecrawl collects web sources and Codex coordinates the process. Through BeatAPI, we assign different models to different stages: a Claude-family model for long-form drafting, GPT-6 Astra for overall planning, DeepSeek for repeatable execution, and GPT-5.6 Sol for editorial QA.

The models produce options. Our standards decide what gets published.

2. Social Data reveals live demand

Search tells us what people look for. Social Data shows how they describe the problem right now.

Every day, we use BeatAPI’s Social Data API to inspect X timelines, trends, post activity, and surrounding conversations. We shortlist discussions that are relevant and gaining attention.

The API does not automatically publish replies. We read the original post and respond only when we can add something specific: an implementation detail, a production constraint, a cost trade-off, or a useful example.

When interest around GPT-6 Astra and 3D workflows rose, we connected relevant conversations to source-linked examples for Blender, Three.js, WebGL, games, and AI-assisted CAD. With MiniMax H3, we focused on practical observations around typography, UI motion, product shots, and natural-language editing.

Replies reveal questions. Short posts test ideas. Long-form articles turn the strongest ideas into complete arguments.

3. Developer stories turn work into proof

Developers do not buy another endpoint. They buy a completed task, lower cost, a more reliable workflow, or fewer integrations to maintain.

Our daily work already produces useful stories: Why did we choose asynchronous tasks? What happens when a provider fails? Why do we use different models for planning, execution, writing, and QA? Which product assumption turned out to be wrong?

One factual source can become an X post, a LinkedIn story, a DEV article, or a deeper engineering write-up. BeatAPI appears naturally because it is the product being built, used, and corrected—not a promotion pasted onto the end.

4. Open source makes the work verifiable

We do not create repositories only because GitHub is a distribution channel. We open-source workflows we actually use.

BeatDesign is our local-first, open-source workspace for AI image and video creation. It connects a Canvas, shared Assets, a video Editor, and MCP access inside one Project.

We use it for real visual workflows, including TikTok-style UGC videos: develop the idea on the Canvas, generate variations through BeatAPI, move useful outputs into Assets, and finish the sequence on the timeline.

Opening the workflow lets the community inspect it, run it, extend it, and tell us what is missing. It also makes BeatDesign our Customer Zero: a real environment for testing BeatAPI inside an agent-driven creative workflow.

The funnel matters more than the channel list

A GitHub star is not a signup. A signup is not an API key. An API key is not a successful task.

The path we now measure is:

Real question → useful asset → relevant visitor → signup → API key → successful task → repeated use → revenue

Search captures existing intent. Social Data reveals live demand. Developer stories turn work into evidence. Open source lets people verify and extend it.

We still do not know which loop will compound fastest. That is precisely why I am documenting the system now—while the decisions are still uncertain and the lessons are still real.

BeatAPI: https://beatapi.io/

Open-source work: https://github.com/BeatAPI

One Visual Rule from a 3.2M-View TikTok — Rebuilt with an MCP Agent

Eric Kang — Tue, 08 Sep 2026 11:33:50 +0000

A “dog as a skateboard” AI clip had about 3.2 million views on TikTok when I checked on September 6, 2026. I wanted to see if an Agent could extract the visual logic, rebuild it from a brief, and carry the result through a local production workflow.

To be clear: the 3.2M views belong to the reference clip, not to my recreation.

TL;DR

I used the viral clip as a reference for an impossible visual premise, not as source footage.
The most important prompt decision was reducing the idea to one invariant: “The Dalmatian's bare back is the only surface beneath her shoes for the entire shot.”
The Agent created and connected the production nodes through BeatDesign MCP.
Seedance 2 Mini generated a 10-second vertical result.
The generated video became a reusable project Asset, then entered a timeline with a BeatDesign brand overlay.
The timeline was exported as a 1080×1920 MP4; a 720×1280 copy was prepared for X.

Viral-video recreation is less about adding adjectives and more about finding the one visual rule the model must not escape.

Start with the contradiction

The reference works because the viewer understands the contradiction immediately: a person appears to ride a dog as if the dog were a skateboard.

The failure mode is equally obvious. A video model can “solve” the impossible scene by inventing a normal skateboard, a saddle, a platform, floating feet, or a second animal. The output may look polished while quietly abandoning the idea.

So the first task was not to describe the city, clothing, camera, or lighting. It was to define the contradiction in a way that could be checked in every frame.

The central rule became:

The Dalmatian's bare back is the only surface beneath her shoes for the entire shot.

Everything else supported that sentence.

Prompt anatomy: one rule, then its evidence

The production prompt was organized into five layers.

1. Physical invariant

The woman must remain upright with both shoes directly above the dog's bare back. No board, platform, saddle, harness, or other riding object may appear.

2. Camera evidence

A low three-quarter side angle must keep the woman's face, full body, both shoes, the complete dog, the step edge, and the landing area visible together.

This was important because an invariant is useless if the camera hides the evidence.

3. One continuous action

The dog approaches a low step, compresses, leaves the ground, completes one rotation beneath the rider, lands, and continues running. The request prohibited cuts, close-ups, and angle changes that could conceal a broken transition.

4. Ordinary visual treatment

The impossible event was framed as casual smartphone footage in a normal downtown plaza. Slight shake, autofocus adjustment, ordinary daylight, and unreactive pedestrians kept it closer to native social video than a glossy commercial.

5. Explicit escape routes

The negative constraints blocked the most likely substitutions:

no skateboard
no wooden deck
no platform or wheels
no saddle or harness
no floating feet
no duplicated person or animal
no anatomy morphing
no cuts or angle changes

Negative constraints were not cleanup. They were part of the scene design.

The Agent-operated production path

The workflow inside BeatDesign was:

reference analysis
→ prompt design
→ generation node
→ Seedance 2 Mini request
→ result Asset
→ timeline
→ brand overlay
→ MP4 render

The Agent handled the Canvas and timeline operations through MCP. The human role was to select the concept, approve the production rule, inspect the generated motion, and decide whether the output was publishable.

The final generation was 10 seconds in a 9:16 format. After success, the video and its submitted prompt remained attached to the same project rather than being reduced to an anonymous downloaded file.

Why lineage matters

For a one-off post, lineage sounds like unnecessary infrastructure. It becomes useful the moment the first result is imperfect.

With the Canvas record intact, I could answer:

Which prompt produced this version?
Which model and duration were used?
Which output was selected for the timeline?
Which Asset contains the unbranded generation?
Which render includes the overlay?
Where should a second attempt branch from?

That makes the recreation reusable. The next experiment can keep the physical rule but change the city, camera height, wardrobe, or final action without rebuilding the whole brief.

Common failures and prompt fixes

Failure	Why it happens	Prompt or workflow fix
A skateboard appears	The model normalizes “ride” into a familiar object	State that the bare back is the only surface and ban decks, platforms, and wheels
Shoes float away from the dog	The relationship is described but not continuously constrained	Require both shoes to remain aligned a few centimeters above the back throughout the action
The dog becomes distorted	Too much motion is requested without an anatomy rule	Specify a healthy normal-sized Dalmatian, four-legged gait, realistic paw contact, and no morphing
A cut hides the jump	The model uses editing to bridge an impossible action	Require one continuous medium-wide view with no cuts or angle changes
The scene looks like an ad	Cinematic language overpowers the UGC premise	Ask for raw smartphone behavior, ordinary daylight, imperfect framing, and natural ambience
The result cannot be revised	Prompt and output live outside a project	Save the generation, Asset, timeline, and render as linked project objects

My sequence for reference-driven video

This is what I follow now when rebuilding the logic of a reference clip:

Write one sentence describing why the clip is instantly understandable.
Identify how a model could cheat or normalize that sentence.
Turn the central relationship into a frame-by-frame invariant.
Choose a camera that visibly proves the invariant.
Define one continuous action with a clear start, transition, and landing.
Add negative constraints for the likely escape routes.
Generate only after the prompt and visible Canvas node have been reviewed.
Keep the raw output and the published render as separate Assets.

What this test does not prove

It does not prove that one prompt will reproduce the same motion across every model or every attempt. Video generation remains probabilistic, and a complex physical action can fail even with a careful brief.

It also does not prove that a recreated concept will inherit the reference's distribution. The source's 3.2M views are context for why the visual premise was worth studying, not a performance claim about the new clip.

Finally, BeatDesign is not an automatic originality or rights checker. Reference analysis still requires human judgment about transformation, attribution, and publication rights.

The broader point

The reusable asset was not the viral clip — it was the invariant extracted from it.

Once the rule, its evidence, the generation record, and the selected output lived in one project, the Agent could operate a real creative workflow instead of producing an isolated answer.

BeatDesign is open source and local-first:

https://github.com/BeatAPI/BeatDesign

BeatDesign is a local, open-source Higgsfield Canvas any MCP agent can drive

Eric Kang — Thu, 03 Sep 2026 07:01:38 +0000

BeatDesign is a local, open-source Higgsfield Canvas. Codex, Claude Code, Cursor, or any other MCP-capable agent can operate the same canvas.

If you have used Higgsfield, you already know the product: an infinite canvas for image and video, branches and references on one board, then a short cut out of those outputs. That canvas is the product. I wanted the Higgsfield Canvas on my disk, under Apache-2.0, without uploading first — and I wanted a general-purpose agent to drive it, not a chatbot trapped inside Higgsfield.

So I built BeatDesign. Same Higgsfield Canvas job. Local project. Open source. Any MCP agent. Upload only when you confirm generation.

The Higgsfield Canvas, without the Higgsfield lock

Higgsfield’s canvas is a closed webpage. Drag in a client product shot or an unreleased campaign, and Higgsfield has the file before you have a generation. The branches live on their server. An idle month still bills. The Higgsfield Canvas is rented.

BeatDesign keeps the Higgsfield Canvas locally. Studio, Canvas, Assets, generation history, and a short-form Editor live in one SQLite-backed Project — a folder you can copy. Import, branch, trim, preview, and export MP4 with no account and no API key. A source file is sent to a provider only after you confirm the run. You pay per generation, not for a month of Higgsfield you did not open.

Local-first does not mean the model runs on your GPU. It means the Higgsfield Canvas stays yours.

A general-purpose agent can operate that canvas

Higgsfield keeps the agent inside Higgsfield. BeatDesign does not embed a proprietary chatbot. It exposes 20 local MCP tools for Projects, Assets, Canvas, Generation, and Editor. Codex, Claude Code, Cursor, or another MCP host inspects and updates the same local Higgsfield Canvas that is open in the browser.

A real loop: you import a local product video. The agent pulls the tail frame, writes the next-shot prompt, and drops the clip on the timeline. You watch the canvas update in the same window. The agent is not clicking Higgsfield pixels. UI writes and MCP writes go through the same Command Kernel, revision checks, and persisted receipts.

A sidebar agent inside Higgsfield can talk. It cannot operate a canvas you own.

You can ignore MCP and still use the canvas by hand. Agent-native is not agent-required.

What exists today

v0.2 is that local Higgsfield Canvas: image/video generation, Canvas branching, shared Assets, timeline trim/split/move, audio fades, selected-range AI redo, and browser-side H.264/AAC MP4 export. No system FFmpeg. Plus 20 MCP tools on the same project.

It is still developer-first: Node.js and pnpm. No signed desktop installer. Captions, transitions, waveforms, speed controls, and multiple named timelines are not in this release. This is not a CapCut replacement, and it does not claim to beat Higgsfield on cinematic templates. It claims one thing: a local, open-source Higgsfield Canvas that any general-purpose agent can drive.

If you already live on the Higgsfield Canvas, clone it and run it locally.

Website: https://design.beatapi.io/
GitHub: https://github.com/BeatAPI/BeatDesign

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

Eric 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.