{"openapi":"3.1.0","info":{"title":"Clipbeat API","version":"1.0.0","description":"Turn a song into a music video for a Clipbeat account. Create a key in Clipbeat Studio settings. Payment comes from the account's credit balance; when it is not enough the API returns 402 with topup_url (agents never enter card details). The lead is always an original AI character. By sending a song you confirm you own it or have the rights to use it. Finished videos can appear on your Clipbeat page. You can hide any video anytime."},"servers":[{"url":"https://api.clipbeat.app"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Personal API key (cb_live_...)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"topup_url":{"type":"string"},"retry_after_sec":{"type":"integer"}},"required":["error","message"]},"Song":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"duration_sec":{"type":["number","null"]},"status":{"type":"string","enum":["processing","ready"]},"lyrics_status":{"type":"string","enum":["processing","ready","failed"]},"created_at":{"type":["string","null"],"format":"date-time"}}},"Video":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","failed","canceled"]},"tier":{"type":"string","enum":["preview","standard","plus","premium"]},"title":{"type":["string","null"]},"aspect":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"progress":{"type":["object","null"],"properties":{"stage":{"type":["string","null"]},"done":{"type":"integer"},"total":{"type":"integer"},"percent":{"type":"integer"}}},"cost":{"type":"object","properties":{"credits_reserved":{"type":"integer"},"credits_charged":{"type":"integer"},"credits_refunded":{"type":"integer"},"usd":{"type":"number"}}},"result":{"type":["object","null"],"properties":{"video_url":{"type":["string","null"]},"poster_url":{"type":["string","null"]},"expires_in_sec":{"type":"integer"}}},"error":{"type":"string"}}}}},"paths":{"/v1/songs":{"post":{"operationId":"importSong","summary":"Import a song from a link (direct .mp3/.m4a/.wav, Google Drive or Dropbox; Suno links are rejected)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","rights_attestation","rights_version"],"properties":{"url":{"type":"string","format":"uri"},"rights_attestation":{"type":"boolean","const":true,"description":"By sending a song you confirm you own it or have the rights to use it. Finished videos can appear on your Clipbeat page. You can hide any video anytime."},"rights_version":{"type":"string","const":"2026-11-21"}}}}}},"responses":{"200":{"description":"Already imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"201":{"description":"Imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/songs/{id}":{"get":{"operationId":"getSong","summary":"Song status (wait for status ready before starting a video)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Song","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/videos":{"post":{"operationId":"createVideo","summary":"Start a video from an imported song (credits are reserved, unused credits are returned)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["song_id"],"properties":{"song_id":{"type":"string","format":"uuid"},"tier":{"type":"string","enum":["preview","standard","plus","premium"],"default":"preview"},"style":{"type":"string","maxLength":600,"description":"World, place and look of the video"},"character":{"type":"string","maxLength":300,"description":"Original AI lead (no real or famous people)"},"aspect":{"type":"string","enum":["16:9","9:16"]},"title":{"type":"string","maxLength":120}}}}}},"responses":{"202":{"description":"Started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (see topup_url)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Song still processing or another video in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Brief rejected or song unusable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listVideos","summary":"Latest videos of the account","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Videos","content":{"application/json":{"schema":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/Video"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/videos/{id}":{"get":{"operationId":"getVideo","summary":"Video status, progress, cost and download link when completed","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pricing":{"get":{"operationId":"getPricing","summary":"Prices per tier (pass song_id for prices by song length)","parameters":[{"name":"song_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Pricing","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/balance":{"get":{"operationId":"getBalance","summary":"Credit balance","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer"},"usd":{"type":"number"},"credits_per_usd":{"type":"integer"},"topup_url":{"type":"string"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}