V2 Character-Based Generation

The V2 API introduces character-based generation, allowing you to create AI characters and use them as input for image editing, video generation, and visual effects — all through a simple character ID.

Key Difference from V1

In V1 APIs, you provide image URLs or base64-encoded images as input. In V2, you first create a character, then reference it by its id in generation requests.

"images": ["6870"]   // V2: character ID
"images": ["https://..."]  // V1: image URL

How It Works

1. List Characters — Browse existing characters.
2. Create a Character — Generate a new AI character from a text prompt.
3. Generate — Apply visual effects to your character.
4. Generate with Advanced Custom — Edit images or generate videos with custom prompts using your character.

---

Characters API

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

Elara Voss (id: 6790)

Julia Nowak (id: 6604)

Flavie Koepp (id: 6593)

---

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

Astrid (id: 6870) — generated from prompt