Trinity-2 Avatars

• 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.
• Play an intro animation when a Simli Auto session opens.

​

Making a Trinity-2 face

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

RATIO=$(grep -i '^target-ratio:' headers.txt | cut -d' ' -f2 | tr -d '\r')
curl -X POST "https://api.simli.ai/faces/trinity?gsVersion=GSA_2.0&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": []
}

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}
	]
}

​

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. Each account’s 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

• POST /compose/token
• POST /static/audio
• POST /auto/token
• POST /auto/start/configurable

{
	"faceId": "YOUR_TRINITY_2_FACE_ID",
	"streaming_width": 1366,
	"streaming_height": 768,
	"avatar_position_x": 0.3,
	"camera": {"zoom": 1.2, "orbit_y_off": 15}
}

​

The camera

​

Moving the camera during a session

pos_y_off, pos_x_off, pos_z_off, zoom, rot_x_off, rot_y_off, rot_z_off, orbit_x_off, orbit_y_off

• Values: send the first 4, the first 7 or all 9 values. Any you leave off have no effect.
• Replacement: each message replaces the whole camera, including the starting camera from the token. Values are offsets from the avatar’s own framing, not from the previous message. Sending 0, 0, 0, 1, 0, 0, 0, 0, 0 goes back to the avatar’s own framing.
• Gliding: the camera cuts to the new setting. To glide instead, add the ASCII tag LERP and one more float32: the number of seconds the move takes. The glide starts from wherever the camera is now, even partway through an earlier glide. A value of 0 or less is a cut.
• Size: a message is 20, 32 or 40 bytes long, or 28, 40 or 48 bytes with LERP.

const CAMERA_FIELDS = [
	"pos_y_off", "pos_x_off", "pos_z_off", "zoom",
	"rot_x_off", "rot_y_off", "rot_z_off",
	"orbit_x_off", "orbit_y_off",
];

// ws is the session's WebSocket. Fields left out of `camera` are neutral.
function sendCamera(ws, camera = {}, lerpSeconds = 0) {
	const values = CAMERA_FIELDS.map((field) => camera[field] ?? (field === "zoom" ? 1 : 0));
	const lerpAt = 4 + 4 * values.length;
	const message = new Uint8Array(lerpAt + (lerpSeconds > 0 ? 8 : 0));
	const view = new DataView(message.buffer);
	message.set(new TextEncoder().encode("CAM_"), 0);
	values.forEach((value, i) => view.setFloat32(4 + 4 * i, value, true));
	if (lerpSeconds > 0) {
		message.set(new TextEncoder().encode("LERP"), lerpAt);
		view.setFloat32(lerpAt + 4, lerpSeconds, true);
	}
	ws.send(message);
}

// Orbit 20 degrees to the right and zoom in a little, over 1.5 seconds
sendCamera(ws, {orbit_y_off: 20, zoom: 1.3}, 1.5);
// Cut back to the avatar's own framing
sendCamera(ws);

import struct

CAMERA_FIELDS = (
    "pos_y_off", "pos_x_off", "pos_z_off", "zoom",
    "rot_x_off", "rot_y_off", "rot_z_off",
    "orbit_x_off", "orbit_y_off",
)


def camera_message(lerp_seconds: float = 0.0, **camera: float) -> bytes:
    values = [camera.get(field, 1.0 if field == "zoom" else 0.0) for field in CAMERA_FIELDS]
    message = b"CAM_" + struct.pack(f"<{len(values)}f", *values)
    if lerp_seconds > 0:
        message += b"LERP" + struct.pack("<f", lerp_seconds)
    return message


# With the Python SDK, send() passes the message through as is
await connection.send(camera_message(orbit_y_off=20, zoom=1.3, lerp_seconds=1.5))

​

Intro animation (Simli Auto)

curl -X POST "https://api.simli.ai/auto/start/configurable" \
	-H "x-simli-api-key: $SIMLI_API_KEY" \
	-H "Content-Type: application/json" \
	-d '{"faceId": "YOUR_TRINITY_2_FACE_ID", "firstMessage": "Hi there!", "introAnimation": "wave"}'