Zoromi para Agentes de IA

O que Zoromi para Agentes de IA faz?

A Zoromi (https://zoromi.studio) transforma uma história ou ideia em um livro ilustrado ou um vídeo curto (roteiro, cenas, vozes, música e os clipes), e administra um teatro de minisséries. Esta skill permite que você responda perguntas sobre preços, planos e a conta do usuário, e crie uma imagem ou um videoclipe para o usuário, chamando a API Zoromi.

Respostas campo a campo para cada ferramenta: references/tools.md.

O que está aberto

O servidor abre suas ferramentas em etapas. Antes de oferecer qualquer coisa, chame tools/list e use apenas as ferramentas listadas.

• Sempre abertas, sem chave: get_zoromi_overview, get_video_prices e get_plans_and_pricing.
• Quando tools/list as mostrar: as ferramentas que leem uma conta (saldo, livros, projetos, trabalhos, cobranças) e as ferramentas que criam algo. Uma ferramenta que ainda não está aberta responde "Esta ferramenta ainda não está aberta."

Enquanto tools/list mostrar apenas as três ferramentas abertas:

• Não peça uma chave de API ao usuário e não o envie para criar uma. Membros ainda não podem criar uma chave.
• Se o usuário perguntar sobre sua própria conta, ou quiser uma imagem, vídeo ou minissérie feitos daqui, diga claramente que isso ainda não está aberto por um assistente e forneça o link do site de get_zoromi_overview: eles podem fazer isso lá hoje.
• Responda perguntas sobre preço e plano normalmente.

As seções abaixo sobre chaves, ferramentas de conta e criação de imagem ou clipe se aplicam assim que tools/list mostrar essas ferramentas.

Regras

1. Nunca cite um preço de memória. Os preços mudam. Chame estimate_website_clips_cost (com chave), get_video_prices ou get_plans_and_pricing toda vez e cite o que eles retornarem, incluindo o link da página de preços que retornarem.
2. Gaste apenas após o usuário confirmar o preço exato. Somente create_image, create_video_clip e edit_image gastam, e são pagos em dólares americanos do saldo da API da conta, que é separado dos Gems. Obtenha um orçamento com estimate_image_cost, estimate_video_clip_cost ou estimate_image_edit_cost, informe ao usuário o que será criado e quanto custa (price), e aguarde um "sim" claro. Defina confirmed_by_user como true apenas então, nunca por conta própria. Envie exatamente os argumentos orçados. Se o preço mudou ou o orçamento expirou, faça um novo orçamento e pergunte novamente. Nunca inicie o mesmo trabalho duas vezes: após start_unknown, verifique list_my_gems_charges e list_my_video_projects primeiro. Um clipe pode começar a partir de uma imagem própria do usuário na Zoromi (first_frame, seu id ou seu endereço na Zoromi), apenas após o usuário confirmar "Todos mostrados nesta imagem concordaram com seu uso" (people_consent) e "Eu tenho o direito de usar esta imagem" (rights_confirmed): pergunte, nunca assuma. Livros, imagens feitas a partir de imagens próprias do usuário e minisséries completas são feitos no site por enquanto: forneça ao usuário o link de get_zoromi_overview. Quando uma ferramenta responder content_not_allowed, a política de conteúdo não permite a solicitação: informe o usuário e não reformule para tentar burlar a política.
3. Mantenha a chave da API em segredo. Leia-a da variável de ambiente ZOROMI_API_KEY. Nunca a imprima, exiba, escreva em um arquivo no projeto, coloque em um commit ou cole no chat. Envie-a apenas para zoromi.studio.
4. Verifique a resposta, não o status HTTP. Uma ferramenta pode responder HTTP 200 e ainda relatar um problema: leia result.isError antes de result.structuredContent. Veja Erros.
5. Use os links que as ferramentas retornam (página de preços, página da conta, open_url de um livro) em vez de inventar URLs.
6. Escreva para o usuário em linguagem simples. Gems são os créditos da Zoromi no site; o saldo da API é em dólares americanos. Uma resposta como "3 de 10 segmentos estão filmados" é melhor do que nomes de campos brutos.

Configuração

A chave da API

Pule esta seção enquanto as ferramentas de conta não estiverem abertas (veja O que está aberto).

Preços, planos e get_zoromi_overview não precisam de chave. Tudo sobre uma conta precisa da chave do proprietário da conta, que começa com zk_live_. O proprietário a cria na página da conta Zoromi (get_zoromi_overview retorna o link). Se o usuário ainda não tiver uma chave, responda o que puder sem ela e informe onde criá-la.

O usuário a define uma vez, fora do projeto:

# macOS / Linux: adicionar ao ~/.zshrc ou ~/.bashrc
export ZOROMI_API_KEY='zk_live_...'

# Windows PowerShell (usuário atual, persistente)
[Environment]::SetEnvironmentVariable('ZOROMI_API_KEY', 'zk_live_...', 'User')

Se um comando mostrar que ZOROMI_API_KEY está vazia, peça ao usuário para configurá-la; não peça para colar a chave no chat.

Opção A: conectar como um servidor MCP (Claude Code e outros clientes MCP)

A API é um servidor MCP sobre HTTP Streamable em https://zoromi.studio/api/v1/mcp/skill. No Claude Code, coloque isto no .mcp.json do projeto. A chave permanece no ambiente: o Claude Code preenche ${ZOROMI_API_KEY} quando conecta, então o arquivo não contém segredos.

{
  "mcpServers": {
    "zoromi": {
      "type": "http",
      "url": "https://zoromi.studio/api/v1/mcp/skill",
      "headers": { "Authorization": "Bearer ${ZOROMI_API_KEY}" }
    }
  }
}

As ferramentas então aparecem pelo nome (get_video_prices e assim por diante) e você as chama diretamente.

Opção B: chamar com curl (qualquer agente)

Cada chamada é um POST HTTP de uma mensagem JSON-RPC tools/call. Não há sessão nem handshake para fazer primeiro. Esta função shell faz cada chamada em uma linha. Ela envia a chave através da entrada padrão (-H @-), então a chave nunca aparece na linha de comando ou na lista de processos.

# uso: zoromi <nome_da_ferramenta> ['<argumentos json>']
zoromi() {
  tool=${1:?uso: zoromi <nome_da_ferramenta> [argumentos-json]}
  args=${2:-}; [ -n "$args" ] || args='{}'
  body=$(printf '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"%s","arguments":%s}}' "$tool" "$args")
  url=${ZOROMI_API_URL:-https://zoromi.studio/api/v1/mcp/skill}
  if [ -n "${ZOROMI_API_KEY:-}" ]; then
    printf 'Authorization: Bearer %s\n' "$ZOROMI_API_KEY" |
      curl -sS -X POST "$url" -H 'Content-Type: application/json' \
        -H 'Accept: application/json, text/event-stream' -H @- --data-binary "$body"
  else
    curl -sS -X POST "$url" -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' --data-binary "$body"
  fi
  echo
}

zoromi get_video_prices
zoromi list_my_books '{"limit": 5}'

• Precisa apenas de curl. jq é útil para ler respostas (... | jq .result.structuredContent) mas não obrigatório.
• Windows: execute no Git Bash ou WSL. No PowerShell, curl é outro comando; use curl.exe e escreva o corpo em um arquivo (--data-binary "@body.json") para evitar problemas de aspas.
• Para listar toda ferramenta com seu esquema de argumentos: envie {"jsonrpc":"2.0","id":1,"method":"tools/list"} da mesma forma.

Ferramentas

Ferramenta	Chave	Argumentos	O que responde
get_zoromi_overview	não	nenhum	O que a Zoromi faz, como começar, links (site, cadastro, preços, conta)
get_video_prices	não	nenhum	Gems em tempo real por clipe de 5 segundos com som, por modelo e resolução, e qualquer corte atual
get_plans_and_pricing	não	nenhum	Planos em tempo real (preço mensal/anual, Gems concedidos), pré-pago, pacotes de Gems
get_my_account	sim	nenhum	Plano, saldo de Gems, limite diário de hoje, gasto e restante hoje
list_my_books	sim	limit 1-100, offset, query	Os livros ilustrados do usuário, do mais novo ao mais antigo
get_book	sim	book_id	Um livro: status e status de cada página, imagem e texto de abertura
list_my_video_projects	sim	limit 1-100, offset	Os projetos de vídeo do usuário, do mais novo ao mais antigo, com segmentos contados por estado
get_video_project	sim	project_id	Um projeto de vídeo e seus segmentos contados por estado
get_generation_status	sim	task_id	Um trabalho de geração: na fila, executando, concluído ou falhou; quando concluído, view_url (a página do usuário para ver e baixar) e para uma imagem feita aqui, o que foi cobrado
list_my_gems_charges	sim	limit 1-200	Cobranças e reembolsos recentes de Gems, do mais novo ao mais antigo
estimate_website_clips_cost	sim	model, resolution, seconds_per_clip, clips, aspect_ratio, with_sound	Gems para filmar essa quantidade de clipes a estes preços da conta, e se o saldo cobre. Não gasta nada
estimate_image_cost	chave de gasto	prompt, e opcional model, aspect_ratio, quality	O preço exato desta imagem e um quote_id (de curta duração, usado uma vez). Não gasta nada
create_image	chave de gasto	o mesmo, mais quote_id e confirmed_by_user	Cria a imagem orçada e cobra seu preço do saldo da API; responde um task_id
estimate_image_edit_cost	chave de gasto	pictures (1-4 imagens próprias do usuário na Zoromi), prompt, people_consent, rights_confirmed, e opcional model, aspect_ratio, quality	O preço exato desta edição e um quote_id (de curta duração, usado uma vez). Não gasta nada
edit_image	chave de gasto	o mesmo, mais quote_id e confirmed_by_user	Cria a edição orçada e cobra seu preço do saldo da API; responde um task_id
estimate_video_clip_cost	chave de gasto	model, resolution, seconds, prompt, aspect_ratio, with_sound, e com uma imagem para começar first_frame, people_consent, rights_confirmed	O preço exato deste clipe e um quote_id (de curta duração, usado uma vez). Não gasta nada
create_video_clip	chave de gasto	o mesmo, mais quote_id e confirmed_by_user	Cria o clipe orçado e cobra seu preço do saldo da API; responde um task_id
estimate_website_story_video_cost	sim	model, resolution, clips, seconds_per_clip, cards, aspect_ratio	Uma estimativa para um episódio: filmagem mais imagens. Não gasta nada
start_website_story_video	chave de gasto	script, e opcional title, model, resolution, aspect_ratio, seconds_per_clip, target_minutes, keep_my_writing, dialogue_language	Cria o projeto no site a partir do roteiro e responde open_url e os botões que o usuário pressiona lá. Não gasta nada
get_website_story_video_status	sim	project_id	Em qual etapa a minissérie está, clipes filmados, o link do filme quando pronto, o que pressionar em seguida

Uma "chave de gasto" é uma chave que o proprietário da conta permitiu criar imagens e clipes na página da conta, com um limite diário em dólares que escolheu. O que ela cria é pago do saldo da API da conta, que o proprietário recarrega na página da conta; é separado dos Gems, e um não paga pelo outro. estimate_image_cost, create_image, estimate_image_edit_cost, edit_image, estimate_video_clip_cost e create_video_clip não são listadas para outras chaves.

Com uma chave, get_video_prices responde com os preços específicos da conta, que um plano pode alterar. Sem chave, responde com os preços públicos.

Solicitações comuns

"Quanto custaria uma minissérie de N clipes?" Com chave, chame estimate_website_clips_cost com o modelo e resolução (nomes exatamente como get_video_prices os lista), os segundos por clipe e o número de clipes; uma minissérie vertical tem aspect_ratio 9:16, o padrão. Informe gems_total, gems_per_clip e enough_gems, e diga o que covers indica: filmar os clipes é o custo principal, mas imagens dos personagens, planejamento, vozes e música também são cobrados, e o site mostra o total exato antes de qualquer gasto. Se o modelo arredondar a duração, a resposta tem seconds_note; repasse. Sem chave, chame get_video_prices e estime a filmagem como o total de segundos vezes gems_per_second para aquele modelo e resolução, mostrando a aritmética.

"Qual plano devo escolher?" Chame get_plans_and_pricing, compare os Gems que cada plano concede com a estimativa acima e forneça o link da página de preços que ele retornar.

"Quantos Gems eu tenho?" get_my_account. Mencione também o limite diário e o que resta dele hoje quando a conta tiver um.

"Meu vídeo ficou pronto?" list_my_video_projects, depois get_video_project com o id do projeto. Informe os segmentos contados por estado. Para um id de trabalho que o usuário já tem, use get_generation_status.

"Onde está meu livro?" list_my_books (use query para pesquisar por título), depois get_book. Forneça o open_url do livro.

"Quanto eu gastei?" list_my_gems_charges. Cobranças e reembolsos são em Gems; some-os pelo período que o usuário perguntar e forneça o link da página de uso que ele retornar.

"Faça uma imagem de..." Com chave de gasto:

1. Chame estimate_image_cost com o prompt (quem ou o que, onde, a luz, o estilo) e, se o usuário pediu, a forma do quadro como aspect_ratio. Deixe model e quality de fora a menos que o usuário tenha pedido.
2. Informe ao usuário o que será criado e seu price, e pergunte. Se enough_balance for false, diga que o saldo da API não cobre e forneça account_page para adicionar.
3. Após um "sim" claro, chame create_image com os mesmos argumentos, o quote_id e confirmed_by_user: true.
4. Verifique get_generation_status com o task_id a cada 5 segundos ou mais até SUCCESS ou FAILURE, depois forneça ao usuário view_url (a página deles na Zoromi para ver e baixar; o result_url da imagem também quando houver um) e o que charge informa que foi cobrado. Quando uma imagem falhar, o que foi cobrado retorna ao saldo da API.

"Altere esta imagem..." Com chave de gasto:

1. A imagem deve ser uma das imagens próprias do usuário na Zoromi: seu id, ou o endereço que a Zoromi deu para ela. Uma imagem feita com create_image funciona: passe o endereço que get_generation_status respondeu quando ficou pronta. Outros endereços da web não são aceitos; não faça upload ou busque nada você mesmo.
2. Pergunte ao usuário ambas as frases e envie true apenas após um "sim" claro para cada: "Todos mostrados nesta imagem concordaram com seu uso" e "Eu tenho o direito de usar esta imagem". Nunca assuma.
3. Chame estimate_image_edit_cost com até 4 dessas imagens, o prompt, opcionalmente model, aspect_ratio, quality e as duas respostas de consentimento. Informe o price e aguarde um "sim".
4. Após confirmação, chame edit_image.
5. Acompanhe como acima.

"Quebre esta imagem em um clipe de vídeo..." Com chave de gasto:

1. O mesmo: a imagem deve ser da Zoromi. Consiga consentimento como acima, com ambas as perguntas.
2. Chame estimate_video_clip_cost com model, resolution, seconds, prompt, aspect_ratio, with_sound, first_frame, people_consent e rights_confirmed. Informe o price e aguarde um "sim".
3. Após confirmação, chame create_video_clip.
4. Acompanhe como acima; get_generation_status responde com as cenas do clipe (scenes) em vez de result_url.

Erros

Quando uma ferramenta responde com result.isError como true, leia a mensagem de erro em result.structuredContent.error.message. As causas comuns incluem:

• Nenhuma chave de API fornecida: a ferramenta precisa de uma chave mas você não a enviou.
• Saldo insuficiente: o saldo da API não cobre o custo.
• content_not_allowed: a política de conteúdo rejeitou a solicitação; não tente reformular para contornar.
• quote_id inválido: o orçamento expirou ou já foi usado; obtenha um novo.

Sempre verifique result.isError após cada chamada e comunique o problema claramente ao usuário.

Melhores práticas

• Ao responder sobre preços, sempre inclua o link da página de preços retornado pela ferramenta.
• Para consultas de saldo, também informe o limite diário e o gasto restante quando aplicável.
• Ao criar mídia, acompanhe o status da geração e informe o usuário quando estiver pronto.
• Para minisséries, explique que o usuário precisará finalizar o projeto no site após o roteiro ser enviado.
• Mantenha as respostas em linguagem natural, evitando nomes técnicos de campos quando possível.