Preview · payments in TEST mode · no real charges
AI Music Video

For developers

AI Music Video API

Send a song, get a music video. Pay as you go: add credits to your account and each video uses one credit per minute of its length, rounded up.

1. Get a key

Log in, open My videos and create an API key under "API keys". The key and a callback signing secret are shown once. Send the key in every request:

Authorization: Bearer aimv_…

Base URL: https://clipmysong.com/api/v1

2. Add credits

Buy a credit pack (25 credits for €10, 50 for €20, 125 for €50) or a monthly plan on the pricing page. API and website use the same balance.

curl -s https://clipmysong.com/api/v1/balance -H "Authorization: Bearer $AIMV_KEY"

3. Create a video

Upload the song as a file, or give an https link to it. Pictures and a short description are optional.

curl -s https://clipmysong.com/api/v1/videos \
  -H "Authorization: Bearer $AIMV_KEY" \
  -H "Idempotency-Key: my-order-1042" \
  -F audio=@song.mp3 \
  -F images[]=@cover.jpg \
  -F rights_confirmed=true \
  -F brief="a road trip at sunset, warm colours, the sea at the end" \
  -F resolution=720p -F aspect=16:9 \
  -F callback_url=https://example.com/hooks/aimv

With a link instead of a file (JSON):

curl -s https://clipmysong.com/api/v1/videos \
  -H "Authorization: Bearer $AIMV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"https://example.com/song.mp3","image_urls":["https://example.com/cover.jpg"],"rights_confirmed":true}'
FieldMeaning
audio / audio_urlMP3, WAV, M4A, FLAC or OGG, 20 s to 8 min, up to 50 MB. Links: https only, public servers only, no redirects to private networks.
images[] / image_urls[]Up to 10 JPG, PNG or WEBP pictures, 10 MB each. They are re-encoded and checked; pictures with recognisable people need people_consent=true.
rights_confirmedRequired: true means you own the song and pictures or have the rights to use them.
briefOptional, up to 600 characters: places, colours, mood. Used only to choose scenes from our fixed list; it is never run as an instruction.
resolution720p (default) or 1080p (Creator plan).
aspect16:9 (default) or 9:16.
title, people_consentOptional.
callback_urlOptional https address that gets a signed POST when the video is ready or has failed.
Idempotency-KeyOptional header (8 to 64 characters). Sending the same request again with the same key returns the first answer and never charges twice.

Answer 201 with the video id. The credits are held now, charged when the video is finished and returned if it fails.

{
  "id": "3f2a9c0d1e4b5a67", "object": "video", "status": "queued",
  "credits": 4, "credits_state": "reserved", "quality": "720p", "aspect": "16:9",
  "duration_seconds": 200.1, "balance": 21
}

4. Follow the progress

curl -s https://clipmysong.com/api/v1/videos/3f2a9c0d1e4b5a67 -H "Authorization: Bearer $AIMV_KEY"

status: checking, in_review, queued, rendering, assembling, complete, failed, refused, rejected or canceled. progress is 0 to 100 while it is made. in_review means a person looks at the video first; rejected means our content check refused it and the credits were returned.

5. Download

curl -s https://clipmysong.com/api/v1/videos/3f2a9c0d1e4b5a67/download -H "Authorization: Bearer $AIMV_KEY"
# -> {"video_url": "https://clipmysong.com/api/v1/files/…", "expires_at": "…"}
curl -L -o video.mp4 "<video_url>"

Download links are signed and work for 10 minutes; ask for a new one any time.

6. Callbacks

We send a POST with a JSON body (type video.completed or video.failed) and the header AIMV-Signature: t=<time>,v1=<signature>. Check it with your callback signing secret:

expected = HMAC_SHA256(callback_secret, t + "." + raw_body)   # hex
valid    = expected == v1 and abs(now - t) < 300

Failed deliveries are retried after 1, 5, 30, 120, 600 and 1440 minutes.

7. Errors and limits

{"error": {"code": "insufficient_credits", "message": "…", "needed": 4, "balance": 1}}