Labsco
imaginepeakstudios logo

Freebeat AI

from imaginepeakstudios

Allows users to generate music videos using Freebeat through MCP

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#social-media#ai-image#ai-video

MCP Documentation

Copy page

freebeat-mcp

MCP server for Freebeat creative workflows.

Use it from MCP clients such as Claude Desktop and Cursor through npx freebeat-mcp.

It currently supports audio and image upload, effect template discovery, AI effect generation, AI music video generation, Open RPC image/video generation, model discovery, and async task polling.

Features

  • Local audio upload or source URL import

  • Image upload for workflows that accept reference images

  • Supported effect template listing

  • AI effect generation

  • AI music video generation

  • Supported image and video model discovery

  • AI image generation and single-image editing

  • AI text-to-video generation

  • Generic task polling and result retrieval

Environment Variables

Variable Required Description FREEBEAT_API_KEY Yes API authentication key

This package depends on Freebeat online services. Available source platforms, effect templates, and generation capabilities may change with backend updates.

Tools

upload_audio

Upload a local audio file or import from a music platform URL.

Currently supported platforms:

  • SoundCloud

  • YouTube

  • Suno

  • Udio

  • TikTok

  • Stable Audio

  • Riffusion

Provide exactly one of file_path or url.

Returns a music_id that can be used by either generate_music_video or generate_effect.

upload_image

Upload one or two images and receive image_urls.

For MV generation, pass the returned image_urls into generate_music_video.reference_image_urls.

For effect generation, the default recommendation is still list_effects.image_url, but you can also upload one image and pass image_urls[0] into generate_effect.reference_image_urls.

list_effects

List supported effects with:

  • effect_id

  • display_name

  • image_url

  • preview_video_url

  • default_music_id

  • default_music_name

  • aspect_ratio

For effect generation, pass:

  • effect_id into generate_effect.effect_id

  • default_music_id into generate_effect.music_id

  • image_url as the default single entry in generate_effect.reference_image_urls

You can use the built-in effect image directly, or replace it with a single uploaded image URL from upload_image.

generate_effect

Start an async effect generation task.

Recommended flow:

  • list_effects

  • optional upload_audio if you want to replace the effect’s default music

  • optional upload_image if you want to replace the effect’s default image

  • generate_effect

  • get_task_status

  • get_task_result only after status is completed

Parameters:

  • effect_id required

  • music_id required, usually default_music_id from list_effects, or a music_id from upload_audio if you want to replace it

  • prompt required, trimmed length must be 1 to 2000

  • watermark optional, default false

  • reference_image_urls required and must contain exactly one image URL; recommended default is list_effects.image_url, but you can also use upload_image.image_urls[0]

Returns a task envelope with:

  • task_id

  • task_type currently effect_generation

  • status

generate_music_video

Start an async MV generation task from a music_id returned by upload_audio.

  • upload_audio

  • optional upload_image

  • generate_music_video

  • get_task_status

  • get_task_result only after status is completed

Parameters:

music_id required, from upload_audio

prompt required, trimmed length must be 1 to 2000

mv_type optional, default abstract

style optional

aspect_ratio optional, default 16:9

resolution optional, default 720

watermark optional, default false

start_ms optional

end_ms optional

reference_image_urls optional

task_id

task_type currently music_video_generation

status

list_models

List supported Open RPC models for either image or video.

  • list_models with type: "image" before generate_image or edit_image

  • list_models with type: "video" before generate_video

  • optional get_model_help for model-specific examples and constraints

Each model entry includes:

  • model_id

  • model, the API model key when one is available

  • display_name

  • commands

  • constraints

get_model_help

Show detailed usage guidance for one Open RPC model.

Parameters:

  • model required, using either a numeric model_id or API model key from list_models

Use this before video generation to confirm required duration, resolution, supported aspect_ratio, and whether generate_audio is supported.

generate_image

Create an async Open RPC image generation batch.

  • list_models with type: "image"

  • optional get_model_help

  • generate_image

  • get_task_status with the returned batch_id

Parameters:

  • model required, from list_models

  • prompt required, trimmed length must be 1 to 2000

  • size optional

  • resolution optional

  • quality optional

  • count optional, default 1

For GPT-Image 2 (model_id 108), the MCP server sends quality: "medium" and resolution: "1024x1024" by default when omitted. If resolution is omitted but size is provided, that size is also sent as resolution for compatibility.

edit_image

Create an async Open RPC single-image edit batch.

  • upload_image or provide an existing image URL

  • list_models with type: "image"

  • optional get_model_help

  • edit_image

  • get_task_status with the returned batch_id

Parameters:

  • model required, from list_models

  • image required, a single image URL

  • prompt required, trimmed length must be 1 to 2000

  • resolution optional

  • quality optional

  • count optional, default 1

generate_video

Create an async Open RPC text-to-video batch.

  • list_models with type: "video"

  • get_model_help

  • generate_video

  • get_task_status with the returned batch_id

Parameters:

  • model required, from list_models

  • prompt required, trimmed length must be 1 to 2000

  • duration required when the selected model declares supported durations

  • resolution required when the selected model declares supported resolutions

  • aspect_ratio optional, validated when the selected model declares supported ratios

  • generate_audio optional, only accepted for models that support generated audio

Video model constraints are validated locally before a request is sent.

get_task_status

Poll a Freebeat async task or Open RPC batch until it reaches a terminal status. Current MCP endpoints return lowercase status values such as pending, completed, and failed; older backends may still return uppercase variants.

For legacy MV/effect tasks, continue polling while the status is still in progress. Only call get_task_result after the status is completed.

For Open RPC image/video batches, pass the returned batch_id as task_id. You can also pass serial_no to query a single batch item. Completed batch items include result URLs directly in get_task_status, so get_task_result is not used for Open RPC batches.

Returns a stable task envelope including:

  • task_id

  • task_type

  • status

  • error_message optional, present when backend reports a failed task

  • error_code optional, present when backend reports a failed task

  • message optional, present when status is completed or failed

  • items optional, present for Open RPC batches and containing image_url, video_url, or edit_images when available

get_task_result

Retrieve the output for a completed task. Only call this after get_task_status returns completed. The response uses a stable envelope with task_id, task_type, status, and result.

If the task is not completed yet, this tool returns error code TASK_NOT_COMPLETED.

If the task has failed, this tool surfaces the backend failure as an error.

For current supported completed MV tasks, result is an object containing:

  • video_url

  • cover_url

Completed effect generation results use the same result object fields:

Last updated on July 2, 2026