Retrieve the list of characters

January 9, 2025 (March 17, 2025)

Table of contents

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

Use hailuoai.video account to retrieve list of generated videos, see Setup MiniMax for details.

This endpoint returns a list of previously created characters, the same list you see when navigating to Subject Reference » Add Reference Character » My Characters.

https://api.useapi.net/v1/minimax/videos/characters/?…

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
Query Parameters

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

  • page is optional, specify the page number. Default 1.

  • pageSize is optional, specify number of items to return. Default 50.

Responses

  • 200 OK

    Field cdnUrl contains a link to the originally uploaded file.
    Field promptImgUrl contains a link to the detected character face from the file mentioned above.

    [
    {
        "characterID": "1234567890",
        "characterType": 1,
        "file": {
            "fileID": "user:user_id-minimax:account-file:file_id",
            "cdnUrl": "https://cdn.hailuoai.video/...jpeg",
            "promptImgUrl": "https://cdn.hailuoai.video/..."
        }
    }
]

  • 400 Bad Request

    {
    "error": "<Error message>",
    "code": 400
}

  • 401 Unauthorized

    {
  "error": "Unauthorized",
  "code": 401
}
Model 
{   // TypeScript, all fields are optional
    characterID: string
    characterType: number
    file: {
        fileID: string
        cdnUrl: string
        promptImgUrl: string
    }
}[]
Examples 
  • curl "https://api.useapi.net/v1/minimax/videos/characters/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 

  • const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/characters/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});

  • import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/characters/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
Try It