Upload audio or an image

November 14, 2026 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Query Parameters
  3. Request Body
  4. Responses
  5. Model
  6. Examples
  7. Try It

Upload a file to an account’s ACE Music Library, sent as the raw request body with its Content-Type:

  • Audio (MP3, WAV, FLAC, OGG, M4A or AAC, up to 100 MB and 8 minutes) becomes a song in the Library. ACE Music transcribes it, reading its lyrics, style, tempo and melody, which took about 15 to 30 seconds in our tests. The answer is that song with its songId, which works as a reference in POST /music: cover it, remix or edit it, mash it up, or let it guide a prompt.
  • An image (JPEG, PNG or WebP, up to 10 MB) returns a mediaId for the images of a prompt in POST /music.

The type is read from the file’s first bytes. The Content-Type you send only has to agree on audio or image. An uploaded file, its songId and its mediaId work only on the account it was uploaded to, so a request that uses them runs there.

Uploaded audio counts against the account’s upload allowance, the total length of audio it keeps: 10 minutes on Free, 30 on Creator and 60 on Artist. When it is used up the API answers 412: delete uploads on acemusic.ai, or move up a plan. Transcribing costs no credits. The song’s own audio downloads with GET /music/download.

https://api.useapi.net/v1/acemusic/files?email=email&title=title

Request Headers
Authorization: Bearer {API token}
Content-Type: audio/mpeg
# Or the file's own type: audio/wav, audio/flac, audio/ogg, audio/mp4, audio/aac,
# image/jpeg, image/png, image/webp
  • API token is required, see Setup useapi.net for details.
  • Content-Type is required, an audio/… or image/… type matching the file.
  • Content-Length is required. Most tools send it for you.
Query Parameters
  • email is optional, the account to upload to. Default: any healthy account.
  • title is optional, the title of an uploaded song, and its file name at ACE Music. Default: upload- with the date and time.
    Maximum length: 80 characters.
Request Body

The file’s bytes, nothing else.

Responses
  • 200 OK

    Audio, transcribed:

    {
      "songId": "user:1234-example@example.com-song:so_7d2e9b4c1a8f4e6d93b0c5a1",
      "taskId": "so_7d2e9b4c1a8f4e6d93b0c5a1",
      "status": "succeeded",
      "title": "paper-boat-demo",
      "model": null,
      "style": "A gentle acoustic indie-folk lullaby at a slow, peaceful tempo. Delicate fingerpicked acoustic guitar with warm ambient pads, and a tender female lead vocal close to the mic.",
      "lyrics": "[verse]\nFold the morning into paper\nSend it down the gutter stream\nSail away, little paper boat\nCarry every quiet dream",
      "instrumental": false,
      "duration": 35,
      "audioUrl": null,
      "playUrl": "https://example.r2.cloudflarestorage.com/…/upload.mp3?X-Amz-…",
      "playUrlExpires": "2026-11-16T01:27:32.000Z",
      "coverUrl": "https://acemusic.ai/data/so_7d2e9b4c1a8f4e6d93b0c5a1-cover.jpg?v=1794685595471",
      "pageUrl": null,
      "created": "2026-11-14T19:46:25.300Z",
      "finished": "2026-11-14T19:46:37.999Z",
      "kind": "upload",
      "score": true,
      "upload": {
        "seconds": 35,
        "bpm": 88,
        "transcription": "done"
      }
    }
    

    An image:

    {
      "mediaId": "user:1234-example@example.com-media:cx_5e8a1f3b9c2d4e7f80a6b4d2",
      "email": "example@example.com",
      "url": "https://acemusic.ai/data/cx_5e8a1f3b9c2d4e7f80a6b4d2.jpg",
      "mime": "image/jpeg",
      "kind": "image"
    }
    
  • 202 Accepted

    Audio that ACE Music was still transcribing after 90 seconds. The body is the song as it stands, the same shape as 200. Read it again with GET /music/songId.

  • 400 Bad Request

    ACE Music refused the file, or the body ended early.

    {
      "error": "Importing the audio: Audio can be up to 8 min long",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "useapi.net ⁝ Unauthorized",
      "code": 401
    }
    
  • 404 Not Found

    {
      "error": "Account example@example.com is not configured",
      "code": 404
    }
    
  • 411 Length Required

    {
      "error": "Content-Length is required (send the file as the raw request body)",
      "code": 411
    }
    
  • 412 Precondition Failed

    The account’s upload allowance is used up: delete uploads on acemusic.ai, or move up a plan.

  • 413 Content Too Large

    {
      "error": "The image file is 11.0 MB: the limit is 10 MB",
      "code": 413
    }
    
  • 415 Unsupported Media Type

    {
      "error": "Content-Type says audio but the file is an image (png)",
      "code": 415
    }
    
    {
      "error": "Send the file as the raw request body with its Content-Type (audio/mpeg, audio/wav, audio/flac, audio/ogg, audio/mp4, audio/aac, image/jpeg, image/png or image/webp)",
      "code": 415
    }
    
  • 422 Unprocessable Entity

    ACE Music could not read the audio. The body is the song with its error.

  • 596 Account Error

    The account is paused, or no account is healthy. Add it again with the current password.

Model

The uploaded file: an image, with the mediaId to send in images, or audio, as a song with its songId.

The uploaded image or song, field by field, and the type it uses (Split)

An image:

{ // TypeScript, all fields are optional
  mediaId: string                // user:<id>-<email>-media:cx_…, the image's id: send it in the `images` of POST /music
  email: string                  // the account it was uploaded to
  url: string | null             // ACE Music's link to the image
  mime: string                   // image/jpeg, image/png or image/webp
  kind: string                   // image
}

Audio, the song (kind: "upload"):

{ // TypeScript, all fields are optional
  songId: string                 // user:<id>-<email>-song:so_…, the song's id: use it as a reference, to split, download or delete
  taskId: string                 // ACE Music's own id of the song (so_…)
  status: 'planning' | 'scoring' | 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted'
                                 // ACE Music's progress on the song
  title: string | null           // the song's title (ACE Music writes one for a prompt request)
  model: string | null           // acemusic-v1, acemusic-v1.1 or ace-step-1.5-xl. null for an uploaded file
  style: string | null           // the style the song was made with (ACE Music writes it for a prompt request)
  lyrics: string | null          // [verse] / [chorus] tagged
  instrumental: boolean | null   // true for a song with no vocals
  duration: number | null        // seconds
  audioUrl: string | null        // public mp3 link, https://acemusic.ai/data/<taskId>.mp3, once the song succeeded.
                                 // It never changes: store this one. null for an uploaded file: get its audio with
                                 // GET /music/download
  playUrl?: string | null        // a direct link to the song's audio for players, valid until playUrlExpires: about an
                                 // hour for a made song (the same mp3 as audioUrl), 24 hours for an upload (its own audio,
                                 // in the format it was uploaded in). Some browsers (Brave) block the redirect behind
                                 // audioUrl: store audioUrl, play playUrl. For about a minute after a song is made it is
                                 // audioUrl itself (ACE Music serves the file directly then). In job records,
                                 // GET /music/{songId} and an audio upload's POST /files answer, not in GET /music. null
                                 // while the song is not finished, or when the link could not be read
  playUrlExpires?: string | null // ISO 8601, when playUrl stops working: read the job or the song again for a fresh one
  coverUrl: string | null        // cover art (jpg)
  pageUrl: string | null         // the song's page on acemusic.ai, when ACE Music made one
  created: string | null         // ISO 8601
  finished: string | null        // ISO 8601
  kind: 'original' | 'cover' | 'mashup' | 'edit' | 'upload'   // how the song was made: original (a prompt or mode
                                 // generate), cover (mode cover, and mode remix too), mashup, edit, or upload (a file
                                 // sent with POST /files)
  score: boolean                 // true when ACE Music already has the song's score (GET /music/score)
  error?: {                      // a failed song
    code?: string                // ACE Music's code, e.g. `ref_no_melody`, `song_not_made`
    message?: string             // ACE Music's own words
    reason?: string              // ACE Music's reason, when it gives one
  }
  refunded?: boolean             // ACE Music gave the credits back for a failed song
  stems?: {                      // splits made with POST /music/stems. Their track links are signed (24 hours) on
                                 // GET /music/{songId}, null elsewhere
    vocals?: Split               // mode vocals: vocal and instrumental
    all?: Split                  // mode all: every stem ACE Music found
  }
  upload?: {                     // an uploaded audio file (POST /files)
    seconds?: number             // its length, counted against the account's upload minutes
    bpm?: number                 // the tempo ACE Music read
    transcription?: string       // done once ACE Music has read its lyrics, style and melody
  }
}

Split: each split in stems of a Song above (vocals, all).

{ // TypeScript
  status?: string                // ACE Music's progress on the split
  tracks: {                      // one per stem
    type?: string                // the stem, e.g. vocals, drums, bass
    url: string | null           // signed mp3 link (24 hours) on GET /music/{songId}, null elsewhere
    duration?: number            // seconds
  }[]
}
Examples
  • curl -X POST "https://api.useapi.net/v1/acemusic/files?title=paper-boat-demo" \
         -H "Authorization: Bearer …" \
         -H "Content-Type: audio/mpeg" \
         --data-binary "@demo.mp3"
    
  • import { readFile } from "node:fs/promises";
    
    const token = "API token";
    const bytes = await readFile("demo.mp3");
    const response = await fetch("https://api.useapi.net/v1/acemusic/files?title=paper-boat-demo", {
      method: "POST",
      headers: { "Authorization": `Bearer ${token}`, "Content-Type": "audio/mpeg" },
      body: bytes
    });
    const song = await response.json();
    console.log(response.status, song.songId, song.lyrics);
    
  • import requests
    
    token = "API token"
    with open("demo.mp3", "rb") as f:
        response = requests.post(
            "https://api.useapi.net/v1/acemusic/files",
            headers={"Authorization": f"Bearer {token}", "Content-Type": "audio/mpeg"},
            params={"title": "paper-boat-demo"},
            data=f.read()
        )
    print(response.status_code, response.json())
    
Try It