NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
Referência das ferramentas

Modelos, créditos e predefinições

Liste os modelos do Nodaro com recursos e preços em créditos, leia saldo e gastos e encontre, salve e aplique predefinições de nó num assistente de IA.

As ferramentas de modelos, créditos e predefinições ajudam um assistente a escolher bem uma geração e a pagar por ela. list_models retorna todos os modelos com seus recursos e preços, check_balance e credit_transactions mostram os seus créditos no Nodaro Cloud, e as ferramentas de predefinições encontram, salvam e aplicam as configurações prontas de um nó.

list_models

Retorna os modelos disponíveis nesta instância do Nodaro, agrupados por tipo e desenvolvedor, com uma ficha de recursos de cada modelo. Chame-a antes de uma ferramenta de geração quando o usuário não tiver escolhido um modelo.

Permissão: nenhuma, sempre visível. Créditos: grátis.

ParâmetroTipoObservações
kindstringimage, video ou audio.
modestringUma operação, como t2i (texto para imagem), i2i, edit, upscale, remove-bg, i2v (imagem para vídeo), t2v, v2v, extend, motion-transfer, lip-sync, video-upscale, tts, music, sfx, stt, voice-design, voice-changer, voice-changer-pro, isolation, dubbing, forced-alignment, video-analysis ou video-audit.
familystringUm desenvolvedor, como Google, OpenAI ou Bytedance.
featuredOnlybooleanSomente o melhor modelo de cada nível, escolhido pela equipe do Nodaro.
priceIdsstring[]Cota preços em vez de listar modelos. De 1 a 50 ids de preço. Somente no Nodaro Cloud. Veja Consultar preços.

Retorna: para cada modelo, o maker como { id, name }, a empresa que o criou, e as proporções, resoluções, qualidades, durações e funcionalidades e, nas edições com créditos, o preço de cada variante. Um modelo que a instância oferece com a própria marca não tem maker. Uma lista recommendations indica os melhores modelos para usos comuns, como texto em imagens ou a imagem realista mais barata. Os modelos com dicas de prompt próprias, como o Seedance 2.0, também trazem promptTips, regras curtas para aplicar antes de uma geração de vídeo. O logotipo do desenvolvedor (logoUrl) não está nesta resposta: ele serve para apps que desenham um seletor de modelos, e GET /v1/models o retorna.

Um modelo cujos tamanhos dependem da proporção ou do fundo também traz as regras de tamanho, como GET /v1/models:

  • resolutionsByAspectRatio lista as proporções em que o modelo renderiza menos tamanhos que resolutions, cada uma com os tamanhos que ele renderiza nela. Por exemplo, o GPT Image 2.5 renderiza 27:16, 16:27, 9:8 e 8:9 só em 1K. Uma proporção que não está na lista renderiza todos os tamanhos.
  • transparentResolution é o único tamanho em que um fundo transparente é renderizado.
  • backgroundOnlyAtTransparentResolution significa que o modelo só aceita a configuração de fundo nesse tamanho.

Escolha um tamanho que a proporção escolhida renderiza. Qualquer outro tamanho roda, e é cobrado, no maior tamanho que a proporção renderiza abaixo do que você pediu.

Um modelo que declara o tamanho usado quando uma chamada não indica nenhum o traz como defaultResolution: 1K no FLUX 3 Klein, 2K no Seedream 5.5 e no MiniMax H3 Image, e 720p no PixVerse V6 Max. Leia este campo em vez de tomar a primeira entrada de resolutions como o padrão.

Cada modelo também tem uma página no catálogo de modelos, com os mesmos preços e mais detalhes.

Consultar preços

Envie priceIds para cotar preços em vez de listar modelos. A ferramenta responde { "prices": { "<id>": … } }, com os mesmos valores de POST /v1/credits/model-costs.

  • Uma chamada de LLM em qualquer modelo é cotada pela chave de preço <feature>:<model id>, por exemplo llm-chat:claude-sonnet-5.5 ou reduce:pick-best-llm:claude-opus-5.5. Acrescente :direct quando a chamada é executada no próprio serviço do fabricante do modelo, como no Modo avançado. Acrescente :effort-<level> para o esforço enviado, nos modelos em que o esforço define o preço.
  • Uma chave de LLM responde { "credits": N, "estimate": true }. O valor é uma chamada típica daquele recurso com aquele modelo. A chamada é cobrada pelos tokens que realmente usou, então mostre o valor como ≈N. Veja Como as chamadas de LLM são cobradas.
  • Um modelo ainda sem preço responde { "error": "llm_model_unpriced" }, e uma execução nesse modelo é recusada.
  • Qualquer outro id responde o preço cobrado, { "credits": N }, ou { "error": "not_priced" }.
  • Uma edição sem créditos recusa a consulta com no_credit_system.

check_balance

Retorna o seu saldo de créditos, dividido em créditos da assinatura e créditos de recarga, com o total. Também retorna o seu limite diário de gastos, a sua cota mensal, o seu nível e o fim do período de cobrança.

Permissão: credits:read. Créditos: grátis. Somente no Nodaro Cloud.

Esta ferramenta não tem parâmetros.

Retorna: o saldo e os detalhes do plano.

  • Quais créditos são usados primeiro. Os créditos da assinatura são gastos primeiro. Eles voltam à cota mensal do plano todo mês, também num plano anual, e os não usados não se acumulam. Se o pagamento de uma renovação falhar, os créditos da assinatura que restam nesse período ficam retidos, e eles voltam quando a renovação é paga. Os créditos de recarga valem por 12 meses após a compra.
  • Pagamento por uso. Um effectiveTier igual a payg significa que você não tem assinatura, mas comprou créditos. Você tem todos os modelos, sem marca d’água e sem limite diário.
  • Contas de cobrança compartilhadas. Numa implantação em que uma única conta de cobrança paga por todos, um cliente conectado não consegue ler o saldo dessa conta. A ferramenta responde payer_balance_jwt_only.
  • Uma implantação com unidade própria. Uma implantação pode mostrar a sua própria unidade em vez de créditos, manter cada saldo em uma carteira externa ou não vender planos. Nela, check_balance retorna o que a exibição de saldo da implantação mostra: available, a sua source (external_wallet, allowance ou balance) e a unit. Um valor que não pôde ser lido é null, nunca 0. Onde a implantação gerencia o saldo, a resposta traz managedBy: "deployment" e uma note, e omite os campos do plano.

credit_transactions

Lista os seus dois registros de créditos: as suas compras e o seu uso.

Permissão: credits:read. Créditos: grátis. Somente no Nodaro Cloud.

ParâmetroTipoObservações
limitintegerDe 1 a 100.
cursorstringO cursor da página anterior de compras.
usage_cursorstringO cursor da página anterior de uso.

Retorna: duas listas.

  • data: as suas compras recentes, como assinaturas, recargas e reembolsos. Cada linha tem type, amount_usd, credits_granted, tier, created_at e receipt_url, o link para o recibo, quando houver. next_cursor as pagina.
  • usage: os seus gastos recentes, uma linha para cada execução que os seus créditos pagaram. São as mesmas linhas que a API REST lista com GET /v1/credits/transactions, com os mesmos campos. Uma página tem no máximo 50 linhas, e usage.next_cursor as pagina por meio de usage_cursor.

Em uma linha de uso:

  • credits_charged é quanto a execução custou. É null enquanto os créditos dela ainda estão reservados, e 0 depois do reembolso. Some este campo para obter o seu gasto.
  • credits_reserved, também credits_used, é a reserva feita quando a execução começou. Uma execução liquidada abaixo da reserva, por exemplo, por causa de uma duração medida ou de um teto para uma nova renderização, ainda mostra a reserva inteira aqui.
  • action, provider, status (reserved, committed ou refunded), metadata, payer e workspaceId são como na API REST. Veja Créditos.

Em uma implantação com unidade própria, os valores em créditos das duas listas estão nessa unidade, e a resposta a indica como unit. amount_usd continua sendo o dinheiro que uma compra custou.

list_node_presets

Lista as predefinições de um tipo de nó: as integradas, como Painel de personagem ou Retrato cinematográfico, e as que você salvou. Uma predefinição é uma configuração nomeada de um nó, com o modelo, o prompt e as configurações dele. Leia a configuração completa de uma predefinição com get_node_preset.

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

ParâmetroTipoObservações
nodeTypestringO tipo de nó, por exemplo generate-image. Obrigatório para incluir as predefinições integradas.
sourcestringall (padrão) para as predefinições integradas e as salvas, factory só para as integradas, custom só para as suas. Sem nodeType, a ferramenta retorna as suas próprias predefinições e uma dica.

Retorna: o nome, o ID, a descrição e o grupo de cada predefinição. Um item também traz estes campos quando eles se aplicam:

  • needsImage: true e minReferences: a predefinição parte desse número de fotos conectadas, por exemplo Folha de referência, Transformações de retrato ou um template que usa {image:N}. Execute-a com esse número de imagens de referência.
  • favorite: true: a predefinição é uma das suas favoritas.
  • previewUrl: uma imagem de exemplo. O assistente do app não a recebe.

get_node_preset

Retorna a configuração completa de uma predefinição: o modelo, o prompt, a proporção, a resolução, a qualidade, o prompt negativo e o texto que ela adiciona antes e depois do prompt. Use-a para aplicar uma predefinição com exatidão, copiando os campos para uma ferramenta de geração ou passando o ID dela como presetId.

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

ParâmetroTipoObservações
nodeTypestringObrigatório. O tipo de nó, por exemplo generate-image.
presetIdstringObrigatório. O ID de uma predefinição integrada, como generate-image/location-board, ou o ID de uma predefinição sua.

Retorna: a configuração da predefinição, com minReferences, needsImage, favorite e previewUrl (null quando a predefinição não tem imagem). Retorna um erro quando o ID não corresponde a nenhuma predefinição.

save_node_preset

Salva uma das suas predefinições de nó. Para criar uma predefinição, passe nodeType, name e data, uma configuração de nó como a que get_node_preset retorna. Para atualizar uma predefinição, passe presetId e só o que muda.

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

ParâmetroTipoObservações
presetIdstringUma das suas predefinições, para atualizá-la. Deixe-o de fora para criar uma predefinição.
nodeTypestringObrigatório para criar, por exemplo generate-image.
namestringObrigatório para criar, com até 120 caracteres. O nome precisa ser único para o tipo de nó; caso contrário, a chamada responde name_taken.
descriptionstringOpcional, com até 500 caracteres.
dataobjectA configuração do nó, com no máximo 64 KB. Obrigatório para criar.
previewUrlstring or nullUma imagem de exemplo: uma imagem já armazenada no Nodaro, como um upload ou um resultado pronto. null a remove.
expectedUpdatedAtstringO updatedAt da predefinição, como você o leu. A atualização é recusada com conflict quando a predefinição mudou desde então.

Retorna: o ID, o nome, needsImage, minReferences, previewUrl e updatedAt da predefinição salva. A mesma ação está disponível como POST /v1/node-presets e PATCH /v1/node-presets/:id.

delete_node_preset

Exclui uma das suas predefinições. As predefinições integradas não podem ser excluídas. Uma predefinição que não é sua responde not_found.

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

ParâmetroTipoObservações
presetIdstringObrigatório. Uma das suas predefinições.
expectedUpdatedAtstringO updatedAt da predefinição, como você o leu. A exclusão é recusada quando a predefinição mudou desde então.

favorite_node_preset

Adiciona uma predefinição aos seus favoritos, ou a remove com favorite: false. A predefinição pode ser integrada, como generate-image/character-board, ou uma das suas. Os favoritos aparecem primeiro na lista de predefinições do editor. Executar a ferramenta duas vezes tem o mesmo efeito que executá-la uma vez.

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

ParâmetroTipoObservações
nodeTypestringObrigatório. O tipo de nó, por exemplo generate-image.
presetIdstringObrigatório. O ID de uma predefinição, de list_node_presets.
favoritebooleanPadrão: true. false remove a predefinição dos seus favoritos.

Nenhuma ferramenta gerencia pastas de predefinições, a ordem das predefinições ou a importação em lote. Esses recursos organizam as listas do editor, e a API REST, o SDK e a CLI os oferecem.

Aplicar uma predefinição a uma geração

generate_image, generate_video, generate_music, generate_speech e text_to_audio aceitam presetId. O Nodaro aplica a configuração da predefinição no servidor, e cada campo que você mesmo informa a substitui. Quando a predefinição contém um prompt, você pode omitir prompt. O texto que a predefinição põe antes e depois do prompt envolve o seu próprio prompt. Em generate_image, uma predefinição é aplicada exatamente como o editor a aplica, e um marcador sem padrão precisa de um valor em variables. Veja Aplicar uma predefinição.

Em generate_speech, uma predefinição ajusta a locução, como a velocidade, a estabilidade e o estilo, e text continua obrigatório. Leia mais sobre predefinições em Predefinições.

Perguntas frequentes

Como um assistente escolhe o modelo certo?

Ele chama list_models, filtrando por tipo e modo, por exemplo image e t2i. A resposta lista as proporções, resoluções, durações, funcionalidades e preços de cada modelo, além de recomendações, como o melhor modelo para texto em imagens.

Um assistente pode ver quantos créditos eu tenho?

Sim, no Nodaro Cloud, se você tiver concedido a permissão de créditos. check_balance retorna os seus créditos da assinatura e de recarga, o seu nível e o seu limite diário.

credit_transactions mostra quanto custou cada geração?

Sim. Além das suas compras, ela retorna o uso, uma linha para cada execução que os seus créditos pagaram. Some credits_charged nessas linhas para obter o seu gasto, porque credits_reserved é a reserva, que pode ser maior.

Como uso uma predefinição de nó pelo MCP?

Encontre o ID dela com list_node_presets e passe presetId para generate_image, generate_video, generate_music, generate_speech ou text_to_audio. Os campos que você mesmo informa substituem os da predefinição.

Um assistente pode salvar uma predefinição de nó para mim?

Sim. save_node_preset cria ou atualiza uma das suas predefinições a partir da configuração de um nó, delete_node_preset remove uma e favorite_node_preset adiciona uma predefinição aos seus favoritos. As três precisam da permissão assets:write.

Última atualização

Nesta página