Characters API

Browse, create, and manage AI characters. Character IDs are used as input for Generate with Visual Effect and Generate with Advanced Custom.

List Characters

Retrieve a paginated list of available characters.

https://open.eternalai.org/v2/characters

curl --location 'https://open.eternalai.org/v2/characters?page=1&limit=10'

Parameter	Type	Required	Description
`page`	integer	No	Page number (starting from `1`). Default: `1`.
`limit`	integer	No	Number of results per page. Default: `50`

info

If no parameters are provided, the API returns a maximum of 50 items. Use page and limit to paginate through all available characters.

Response Example

{
    "result": [
        {
            "id": 6790,
            "username": "elara_voss",
            "display_name": "Elara Voss",
            "description": "former bartender, current overthinker. will judge your movie taste but make you a great cocktail to make up for it.",
            "avatar_url": "https://cdn.eternalai.org/imagine/4e006263-b6f9-47fb-9fb2-d160d3448e2d.jpg",
            "age": 25,
            "gender": "female",
            "status": "approved",
            "category": "default"
        }
    ]
}

Parameter	Type	Description
`id`	integer	Character ID — used as input in generation requests.
`username`	string	Unique username of the character.
`display_name`	string	Display name of the character.
`description`	string	Short bio/description of the character.
`avatar_url`	string	URL of the character's avatar image.
`age`	integer	Age of the character.
`gender`	string	Gender of the character (e.g. `"female"`, `"male"`).
`status`	string	Status of the character (e.g. `"approved"`, `"pending"`).
`category`	string	Category of the character (e.g. `"default"`, `"internal"`).

Sample Characters

Create a Character

Generate a new AI character from a text prompt. The character's appearance, name, and bio are automatically generated.

https://open.eternalai.org/v2/character/create

curl --location 'https://open.eternalai.org/v2/character/create' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data '{
    "prompt": "A brilliant Norwegian student who has carved out space for herself in male-dominated fields through sheer determination."
}'

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description of the character you want to generate.

Response Example

{
    "request_id": "6870",
    "result": {
        "id": 6870,
        "username": "astrid",
        "display_name": "Astrid",
        "description": "",
        "avatar_url": "",
        "age": 20,
        "gender": "female",
        "status": "pending",
        "category": "internal",
        "type": "character"
    },
    "data": null,
    "error": null
}

info

The character is created asynchronously. The initial response will have status: "pending" with empty description and avatar_url. Use the Poll for Character Result API below to get the completed character.

Poll for Character Result

Poll the character creation status using the character's id (not request_id).

https://open.eternalai.org/v2/character/poll-result/{CHARACTER_ID}

curl --location 'https://open.eternalai.org/v2/character/poll-result/6870'

Parameter	Type	Required	Description
`CHARACTER_ID`	integer	Yes	The `id` from the character creation response (path parameter).

Response Example (on success)

{
    "status": "success",
    "result": {
        "id": 6870,
        "username": "astrid",
        "display_name": "Astrid",
        "description": "engineering student. probably overthinking a bridge design or where to find the best coffee in oslo. hiking counts as a personality trait here, right? 🇳🇴",
        "avatar_url": "https://cdn.eternalai.org/dating_media/2026/03/31/bd61d557-bd70-4e59-a511-9b9c876e2627.jpg",
        "age": 20,
        "gender": "female",
        "category": "internal"
    },
    "data": null,
    "error": null
}

Generated Character

List Characters​

Create a Character​

Poll for Character Result​

List Characters

Create a Character

Poll for Character Result