create_character, once for each character. The prompt is a
name, a persona, an optional speaking_style, and an optional refusal_reply. After that, you
can talk to the character with say or over the mic track. This page covers each of these inputs
and what to expect in a turn.
Choose the image
The character looks like the image that you upload, so the image is the most important input:- Use one clear, front-facing picture of one person or character.
- The model crops the centre of the image to
aspect_ratio. The character looks like the cropped image, so keep the face and shoulders near the middle. - Match the shape of the image to the call. Use a tall image for
9:16(720 × 1280, the default) and a wide image for16:9(1280 × 720). - Use PNG, JPEG, or WEBP, at most 20 MiB and 40 megapixels.
Write the persona
The persona tells who the character is and how it behaves. It can have up to 4,000 characters. Write what the character knows and what it does, as facts about it. Do not write stage directions, because the character can read them aloud.You are Ava. (Smiles warmly and tilts her head.) You are a photographer. *pauses thoughtfully*
You are Ava, a street photographer in an old town. You have shot its markets and alleys for ten
years. You love morning light, film cameras, and the people who let you take their picture. You
answer questions about photography in plain words and ask about the other person’s photos.
Leave gestures to the character. The character makes gestures by itself and reports each one in a
character_action message.
The character does not speak first. If you want an opening line, send it with say after
speech_ready is true.
Name the character
name has up to 20 characters. The character uses this name when it introduces itself, so use the
name that you want to hear.
Set the speaking style
speaking_style sets the language, the tone, and the length of replies. It can have up to 1,000
characters. If you leave it blank, the character uses short, natural sentences in the language
that the user speaks. If you want a different style, set speaking_style:
Answer in English even if asked in another language. Warm and a little dry. One or two sentences
per answer.
Pick a voice
list_voices returns every voice, with a description and the languages that it speaks. It also
returns default_voice. The default voice, marin, is a natural voice that speaks most languages.
The voices whose names start with saturn_zh_ are Chinese character voices. They also speak
English, but with a strong Chinese accent.
Pass a voice from the list to create_character. To use the default voice, leave voice blank.
If the list does not have the voice, the model refuses create_character with invalid_voice.
Set a refusal reply
The generation service applies its own content policy to the image, the persona, and what is said to the character. When the service declines a turn, the character sendsinput_declined. Then the
character says its refusal_reply instead of an answer. If you leave refusal_reply blank, the
character politely changes the subject. You can also write up to 500 characters for the character
to say in its own voice:
Let’s keep this about pictures. Want to hear about the best light in the old town?
Talk to the character
You can reach the character in two ways. Both needspeech_ready to be true:
saysends one turn of text, up to 800 characters and 800 bytes of UTF-8 (about 260 Chinese characters). The reply issaidwith aprompt_id.miccarries your speech. Publish it beforestart_call. The character then answers your speech without a command.