Trinity-2 Avatars

Trinity-2 is our newest avatar generation. A Trinity-2 avatar is built waist-up, torso and both hands included, from a single photo. Its sessions can also do things the older generations can’t:

Pick the video’s size and shape. Square, landscape or portrait, at any size from 512 pixels up.
Place the avatar on the canvas. Put it anywhere on the frame instead of in the bottom centre.
Set a starting camera, then move it live. Zoom, pan, tilt, roll and orbit around the avatar, as a cut or as a smooth glide. See Camera.
Play an animation on command. Coming soon to Simli Compose. See Animations.
Show your own background or foreground behind or over the avatar, and swap it live. See Backgrounds.

Everything else works as before: the same session token, the same WebSockets and the same audio format (PCM16, 16 kHz, mono). Trinity-1 and legacy faces ignore every setting on this page and keep their own frame size (512x512 for Trinity-1).

Making a Trinity-2 face

Trinity-2 is the default: the two calls below make a Trinity-2 face as they are. Accounts created before October 26, 2026 can still make a Trinity-1 face by passing gsVersion=GSA_1.0 to both calls; newer accounts get a 403 for it.

Reframe the photo

Send the photo to POST /faces/trinity/preprocess. For Trinity-2 it is reframed to show the person waist-up, with the torso and both hands, on the photo’s own background.The photo must be a JPEG, PNG or WEBP under 5MB and at least 512x512. It needs a person facing the camera, and their head must be at least 15% of the image height.

curl -X POST "https://api.simli.ai/faces/trinity/preprocess" \
	-H "x-simli-api-key: $SIMLI_API_KEY" \
	-F "image=@portrait.jpg" \
	-D headers.txt -o framed.png

The warnings header is a JSON array of advice; the image can still be used when it isn’t empty.Not happy with the result? Run it again with retry=true to render at higher quality. That takes about 160 seconds instead of 25.

Start the generation

Post the reframed image to POST /faces/trinity, with the TARGET-RATIO value in the target-ratio header. If you pass gsVersion, pass the preprocess call’s: the two generations frame the image differently.

RATIO=$(grep -i '^target-ratio:' headers.txt | cut -d' ' -f2 | tr -d '\r')
curl -X POST "https://api.simli.ai/faces/trinity?face_name=my_avatar" \
	-H "x-simli-api-key: $SIMLI_API_KEY" \
	-H "target-ratio: $RATIO" \
	-F "image=@framed.png"

{
	"message": "<place in the queue>",
	"face_id": "<new face id>",
	"dispatch_after": 1792412345,
	"warnings": []
}

You can skip the preprocess step and post a photo without a target-ratio header. The image is then preprocessed here automatically first, which adds about 25 seconds.

Wait for it to finish

Creating a Trinity-2 face usually takes about 4 hours.Poll GET /faces/trinity/generation_status with the face_id until status is completed (or failed). The states are pending, processing, completed, failed and not_found.

curl "https://api.simli.ai/faces/trinity/generation_status?face_id=$FACE_ID" \
	-H "x-simli-api-key: $SIMLI_API_KEY"

{
	"status": "pending",
	"queue_position": 2,
	"face_id": "<face id>",
	"generations": [
		{"face_id": "<face id>", "status": "pending", "queue_position": 2, "dispatch_after": 1792412345}
	]
}

Without face_id, generations lists every generation of yours that is still tracked, oldest first. The top-level fields only describe the most recent one, so if you run several generations at once, read generations. Completed and failed generations stay in the list for 24 hours.

Trinity-2 generations and spacing

They use Trinity-2 generations, not face slots. Trinity-1 faces take one of your plan’s face slots. Trinity-2 faces use your Trinity-2 generations instead: one is used when the face is built, and a failed build uses none. A generation that is still queued or building holds one until it finishes. When you have none left, both calls return 403.
Generations start at least 10 minutes apart. Your Trinity-2 generations start at least 10 minutes apart. A request sent sooner is still accepted straight away, but it waits in the queue. While it waits, dispatch_after gives the Unix time (in seconds) when it can start. The field is left out when the generation isn’t held.

Framing the video

Four fields set the video’s size and where the avatar sits in it. They are accepted, together with the starting camera and background_id / foreground_id, by:

Field	Default	Meaning
`streaming_width`	`768`	Width of the video in pixels, at least 512
`streaming_height`	`768`	Height of the video in pixels, at least 512
`avatar_position_x`	`0.5`	Where the avatar sits across the canvas, from 0 (left) to 1 (right)
`avatar_position_y`	`1.0`	Where the avatar sits down the canvas, from 0 (top) to 1 (bottom)

Width and height together must make a 1:1, 16:9 or 9:16 frame. They only need to be within a pixel of the exact ratio, so 1366x768 counts as 16:9. Any other shape, a side under 512 or a position outside 0 to 1 gets a 422, even for faces that ignore framing. A canvas larger than the avatar’s frame is filled out with the avatar’s background, and a smaller one crops a window out of it. An uploaded background is cropped to fill the canvas instead.

POST /compose/token

{
	"faceId": "bf13113a-355a-4d97-8b90-4edccd1da7b2",
	"streaming_width": 1366,
	"streaming_height": 768,
	"avatar_position_x": 0.3,
	"camera": {"zoom": 1.2, "orbit_y_off": 15}
}

Simli Auto agents don’t store framing. To frame an agent’s session, put the framing fields in its POST /auto/token request. The session uses the framing from its token, background and foreground included.

Get Started

Integrations

Simli SDKs

Starter repos

Advanced: Custom Simli Client

Links

Trinity-2 Avatars

Making a Trinity-2 face

Trinity-2 generations and spacing

Framing the video

​Making a Trinity-2 face

​Trinity-2 generations and spacing

​Framing the video

Making a Trinity-2 face

Trinity-2 generations and spacing

Framing the video