AI Detection – REST API

Audio-intelligence endpoints help you classify a track and generate artwork before you submit. All require authentication and operate on a file you have already uploaded (see Uploads).

AI Song Detection

curl -X POST https://once.app/v1/audio/ai-detection \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "file_url": "<fileUrl>", "file_name": "track.wav" }'

Body: { "file_url", "file_name"?, "release_id"?, "conversation_id"?, "track_index"? }.

Returns containsAi, aiScore, predictedModel (e.g. Suno, Udio), and cached. Results are cached per file. This is the same classifier that determines billing: an AI-detected song bills at 2 credits at submission.

Registry match (ACR check)

curl -X POST https://once.app/v1/audio/acr-check \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "file_url": "<fileUrl>" }'

Same body as AI detection. Runs a registry-match check (Pex Search / Identify Music) and returns matched plus bestMatch { title, artist, isrc, queryMatchPercentage, confidence, dspLinks[] }. matched is only true when queryMatchPercentage is greater than 10. If a match surfaces, confirm the user owns or controls the rights before submitting.

Every audio upload (including POST /v1/files/from-url) already runs this check in the background right after the file is stored, usually within a minute. The result is cached per fileUrl, so your first acr-check call on a fresh upload normally returns that stored result with cached: true. That is expected: it is the real check of that exact file, not a stale result from another upload. No wait is required after import, and there is no force-refresh; uploading the file again gives a new fileUrl that is checked from scratch.

Cover art generation

curl -X POST https://once.app/v1/cover-art \
  -H "Authorization: Bearer $ONCE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "neon synthwave skyline at dusk" }'

Body: { "prompt", "base_file_url"?, "base_image_base64"?, "return_base64"?, … }. Generate (or iteratively edit) AI album art. Returns a square 3000×3000 PNG stored in your cover-art bucket, with a fileUrl ready to attach to a release. Pass base_file_url or base_image_base64 to refine an existing image. Rate limited (default 5 per 2 minutes).

Uploads Releases