Personagens

As ferramentas de personagens permitem que um assistente crie e use os personagens da sua biblioteca do Estúdio de personagens (Character Studio): pessoas ou figuras com aparência fixa, que continuam iguais em todas as imagens e vídeos. O assistente cria um personagem, gera e aprova o retrato dele, adiciona variações como expressões, poses, ângulos e iluminação, anima o personagem em clipes de movimento e passa as imagens dele como referência para outras gerações. Leia Estúdio de personagens para fazer o mesmo trabalho no app.

O ciclo de vida de um personagem

list_characters

Lista os seus personagens, dos atualizados mais recentemente para os mais antigos, com o nome, a descrição, o retrato, o número de variações de cada tipo e o texto de identidade de cada um. Os personagens arquivados ficam de fora. Sem search, a ferramenta retorna só a primeira página, então busque pelo nome quando o usuário citar um personagem.

Permissão: assets:read. Créditos: grátis.

Retorna: os personagens. Chame get_character para obter as URLs das imagens.

get_character

Retorna um personagem completo: cada expressão, pose, movimento, ângulo da cabeça, ângulo do corpo e variação de iluminação, com o nome e a URL. Também retorna as fotos de referência e as URLs de referências da vida real, quando uma variação as tem.

Permissão: assets:read. Créditos: grátis.

Retorna: o personagem, incluindo updatedAt para update_character. Um erro quando o personagem não existe ou não é seu.

create_character

Cria um personagem com a identidade dele. Ele ainda não tem retrato: gere um em seguida com generate_character.

Permissão: assets:write. Créditos: grátis.

Retorna: o ID do novo personagem.

update_character

Altera a identidade de um personagem. Só são gravados os campos que você informar.

Permissão: assets:write. Créditos: grátis.

Retorna: uma confirmação, ou um erro de conflito quando expected_updated_at está desatualizado.

approve_portrait

Transforma um resultado concluído de generate_character no retrato do personagem e faz um modelo de visão descrevê-lo, para preencher a descrição canônica do personagem.

Permissão: assets:write. Créditos: uma execução curta de LLM para a descrição.

Retorna: a URL do retrato e a descrição. Quando a descrição falha, o retrato é definido mesmo assim e a descrição fica vazia; execute recaption_character.

recaption_character

Faz o modelo de visão descrever de novo o retrato atual e salva a nova descrição canônica. Use-a depois de trocar o retrato ou quando a descrição não estiver certa.

Permissão: assets:write. Créditos: uma execução curta de LLM.

Retorna: a nova descrição. 400 no_portrait quando o personagem não tem retrato.

generate_character

Gera um retrato do personagem (kind: "main") ou uma variação dele (kind: "asset").

Permissão: workflows:execute. Créditos: o preço do modelo de imagem.

Retorna: um ID de job. Para um retrato, passe o job para approve_portrait quando gostar do resultado.

generate_character_motion

Anima um personagem num clipe de movimento curto, a partir de uma das imagens dele.

Permissão: workflows:execute. Créditos: o preço do modelo de vídeo.

Com attach_to_character_id, a imagem de origem é escolhida nesta ordem: o seu source_image_url, o ângulo frontal do corpo do personagem, qualquer outro ângulo do corpo e, por fim, o retrato. Uma imagem de corpo inteiro se move muito melhor do que um retrato da cabeça, então gere primeiro os ângulos do corpo.

Retorna: um ID de job. O cartão reproduz o clipe quando ele fica pronto.