Create a character

October 16, 2026

Table of contents

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

https://api.useapi.net/v1/mureka/music/characters

Create a character, the same as Create Character on mureka.ai. A character is a reusable singer: a voice plus a default song description. Pass its id as character_id to POST /music/create-advanced, together with your lyrics and a desc style, and the song is sung in that voice.

Build a character from either:

  • your own voice clip, uploaded with POST /files/vocal (about 30 seconds of clear singing works best), or
  • a song you generated, by its song_id.

Creating a character is free and takes under a second. The character is ready to use right away.

Characters are public on mureka.ai unless you create them with private: true. You can change that later with POST /music/characters-publish. List your characters with GET /music/characters and delete them with DELETE /music/characters.

You can also use a voice without creating a character: POST /music/create-advanced accepts vocal_id together with desc.

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body 
{
    "account": "12345678901234",
    "vocal_id": 166746659094530,
    "name": "Scarlett",
    "bio": "A clear, articulate mid-range female voice.",
    "tags": ["Female", "Powerful"],
    "desc": "An intimate mid-tempo acoustic pop song with soft piano and a clear female lead vocal."
}

  • account is optional when only one account is configured or when song_id is provided. However, if you have multiple accounts configured and song_id is not provided, this parameter becomes required.

  • vocal_id is optional, the id returned by POST /files/vocal.

  • song_id is optional, a song you generated, as returned by GET /music or any create endpoint. The song’s own account creates the character.

    Specify vocal_id or song_id, but not both.

  • name is required.
    Maximum length: 50 characters.

  • bio is optional, a short description of the voice.
    Maximum length: 1000 characters.

  • tags is optional, an array of strings or one comma-separated string, up to 10 tags.
    mureka.ai offers Female, Male, Warm, Airy, Bright, Smoky, Soft, Powerful, Smooth, Whispery.

  • desc is optional, the character’s default song description, which mureka.ai shows with the character.
    Maximum length: 1000 characters.

  • private is optional (default: false).
    true keeps the character visible only to you. Otherwise it is published on mureka.ai.

Responses

  • 200 OK

    Use id as character_id. A private character has no is_published field.

    {
    "id": 166751507709953,
    "name": "Scarlett",
    "bio": "A clear, articulate mid-range female voice.",
    "tags": [
        "Female",
        "Powerful"
    ],
    "avatar": "https://static-cos.mureka.ai/cos-prod/mureka/static/img/<id>.jpg",
    "is_published": true,
    "user_id": 12345678901234,
    "published_at": 1792191715,
    "created_at": 1792191715,
    "asset_id": 166751507578881,
    "showcase_edit_range": {},
    "song_description": "An intimate mid-tempo acoustic pop song with soft piano and a clear female lead vocal."
}

  • 400 Bad Request

    {
  "error": "Please specify vocal_id or song_id but not both",
  "code": 400
}

  • 401 Unauthorized

    {
  "error": "Wrong username/password combination.",
  "code": 401
}

  • 403 Forbidden

    The account’s Mureka plan does not include characters.

    {
  "error": "low vip level (6335)",
  "code": 403
}

  • 596 Account Error

    Returned when the account has an error state preventing API calls.

    {
    "error": "Session refresh failed 2026-01-19T14:31:15.000Z, manual update required",
    "code": "REFRESH_FAILED"
}

    Possible error codes:

    • ACCOUNT_ERROR - Account has a blocking error
    • REFRESH_FAILED - Automatic token refresh failed
    • REFRESH_IN_PROGRESS - Token refresh already in progress, retry shortly
    • SESSION_EXPIRED - Session expired and no auto-refresh available
    • COOKIE_EXPIRED - Google cookie has expired

    To resolve, update your account configuration via POST /accounts.

Model 
{
    id: number                     // character_id for POST /music/create-advanced
    name: string
    bio?: string
    tags?: string[]
    avatar?: string
    is_published?: boolean         // left out when the character is private
    published_at?: number          // Unix seconds
    created_at?: number            // Unix seconds
    user_id?: number
    asset_id?: number
    showcase_edit_range?: object
    song_description?: string      // the desc you sent
}
Examples 
  • curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/mureka/music/characters \
     -d '{"account": "…", "vocal_id": …, "name": "Scarlett", "tags": ["Female", "Powerful"]}'

  • const account = "12345678901234";
const vocal_id = 166746659094530;
const apiUrl = `https://api.useapi.net/v1/mureka/music/characters`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  account, vocal_id, name: 'Scarlett', tags: ['Female', 'Powerful']
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

  • import requests
account = "12345678901234"
vocal_id = 166746659094530
apiUrl = f"https://api.useapi.net/v1/mureka/music/characters" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "account": account,
    "vocal_id": vocal_id,
    "name": "Scarlett",
    "tags": ["Female", "Powerful"]
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
Try It