Nós
Execute qualquer nó do Nodaro com POST /v1/<node-type>, descubra nós, modelos e valores de seletores e guie o prompt com referências e IDs de direção.
Uma execução de nó chama um nó do Nodaro diretamente, sem montar um workflow: você envia POST /v1/<node-type> com as configurações do nó no corpo. Todos os nós de geração seguem esse formato, de generate-image e generate-video a text-to-speech, e os endpoints de descoberta informam quais nós, modelos e configurações existem. A maioria das execuções de nó é assíncrona: a resposta é um jobId, que você consulta periodicamente até o resultado ficar pronto.
Executar um nó
A rota de um tipo de nó é POST /v1/ seguido do tipo, e o corpo são as configurações do nó em JSON:
POST /v1/generate-image
Authorization: Bearer ndr_…
Content-Type: application/json
{ "prompt": "a lighthouse in a storm, oil painting", "provider": "nano-banana-pro", "aspectRatio": "3:4" }O que volta depende do nó:
- Os nós de geração respondem
200com{ "jobId": "…" }. O processamento roda em um worker, e você consulta a tarefa periodicamente comGET /v1/jobs/:id/statusaté o status sercompleted. Veja Tarefas. - As gerações de imagem e de vídeo podem incluir
adjustments, uma lista das configurações que o servidor corrigiu para o modelo escolhido.generate-videoegenerate-imagetambém podem incluirwarnings. Veja Correções de parâmetros. - Os nós inline, como
combine-text, retornam o resultado completo na hora, semjobId. - Os extratores, como
web-scrape, também respondem na hora. A resposta traz umjobId, para o seu histórico, e também os próprios dados.
Uma geração reserva créditos quando começa. Quando a conta não tem créditos para cobrir a execução, a chamada retorna 402 insufficient_credits.
Nós com um caminho mais longo
A maioria dos nós de texto que chamam um modelo de linguagem segue a mesma regra POST /v1/<node-type>: generate-script, image-critic, qa-check e describe-to-picker. Alguns outros são registrados em um caminho mais longo:
| Tipo de nó | Rota |
|---|---|
llm-chat | POST /v1/llm-chat/generate |
after-effects | POST /v1/after-effects/generate |
motion-graphics | POST /v1/motion-graphics/generate |
lottie-overlay | POST /v1/lottie-overlay/generate |
3d-title | POST /v1/3d-title/generate |
image-to-text | POST /v1/image-to-text/describe |
video-composer | POST /v1/scene-graph/generate |
O client.nodes.run(type, params) do SDK e o nodaro nodes run da CLI enviam cada um desses tipos de nó para a rota própria dele por você. Veja Executar nós.
As rotas de modelo de linguagem aceitam dois campos opcionais:
reasoningEffort:none,low,medium,high,xhighoumax, conforme o modelo. Omita o campo, ou escolha um nível que o modelo não aceita, para usar o padrão do próprio modelo. O esforço não tem preço próprio. A chamada é cobrada pelos tokens que usa, então um esforço maior só custa mais pelo raciocínio que escreve. Em um modelo Claude, qualquer esforço executa a chamada na API da própria Anthropic, pela tarifa dessa via.advancedMode: true: para modelos Gemini e Claude. A requisição roda na API do próprio fabricante do modelo, a única via em quetemperature,maxTokense toda a faixa de raciocínio têm efeito. A chamada é cobrada pela tarifa por token dessa via. Um modelo sem essa via retorna400 advanced_mode_unsupported. Enquanto o provedor do próprio modelo não aceita requisições, a requisição é recusada em vez de rodar na via padrão, onde os controles dela não teriam efeito. A resposta é400 advanced_mode_unavailableantes de qualquer cobrança, ou502 advanced_mode_unavailableno meio da chamada. Uma recusa no meio da chamada é reembolsada, a menos que o provedor tenha cobrado a tentativa. Desative o Modo avançado para executar o modelo na via padrão dele.
No POST /v1/llm-chat/generate, um modelo lê um quadro por segundo de um vídeo de referência. referenceVideoFps (acima de 0, até 24) pede mais quadros. Ele precisa de advancedMode: true em um modelo Gemini, ou a chamada retorna 400 video_fps_needs_advanced_mode. Mais quadros são mais tokens de entrada. Veja Gerar texto - qualquer LLM.
O describe-to-picker responde com o resultado na mesma requisição, e também pode transmitir a resposta como eventos enviados pelo servidor (server-sent events). Veja Descrever para seletor. Os campos de generate-script estão em Gerar roteiro.
Exemplo: gerar uma imagem
Iniciar a tarefa
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a knight on a hill at dawn, cinematic",
"provider": "nano-banana-pro",
"aspectRatio": "16:9",
"resolution": "2K"
}'{ "jobId": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10" }import { createClient, StaticTokenAuth } from '@nodaro/sdk'
const client = createClient({
baseUrl: 'https://app.nodaro.ai',
auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})
const result = await client.nodes.run('generate-image', {
prompt: 'a knight on a hill at dawn, cinematic',
provider: 'nano-banana-pro',
aspectRatio: '16:9',
resolution: '2K',
})nodaro nodes run generate-image \
--param prompt="a knight on a hill at dawn, cinematic" \
--param provider=nano-banana-pro \
--param aspectRatio=16:9 \
--param resolution=2KConsultar a tarefa periodicamente
Peça o status da tarefa a cada 2 a 5 segundos, até ele ser completed ou failed:
curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
-H "Authorization: Bearer $NODARO_API_KEY" | jq -r .data.statusLer o resultado
Uma tarefa de imagem concluída traz a URL da imagem em output_data.imageUrl. Uma tarefa de vídeo usa videoUrl, uma de áudio usa audioUrl, e muitas tarefas também trazem um thumbnailUrl.
{
"data": {
"id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
"status": "completed",
"progress": 100,
"output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
"error_message": null
}
}O SDK e a CLI podem fazer a consulta periódica por você:
const output = await client.nodes.runAndWait('generate-image', {
prompt: 'a knight on a hill at dawn, cinematic',
provider: 'nano-banana-pro',
})
console.log(output.imageUrl)
// Several candidates at once, in input order:
const results = await client.nodes.runMany('generate-image', [
{ prompt: 'a knight on a hill, sunrise' },
{ prompt: 'a knight on a hill, golden hour' },
{ prompt: 'a knight on a hill, blue hour' },
])
for (const { jobId, output } of results) console.log(jobId, output.imageUrl)nodaro nodes run generate-image \
--param prompt="a knight on a hill at dawn, cinematic" \
--param provider=nano-banana-pro \
--watch --json | jq -r '.output_data.imageUrl'Por padrão, runAndWait faz a consulta periódica a cada 2.000 ms, por até 15 minutos. Mude isso com pollMs e maxMs, interrompa com um AbortSignal em signal e acompanhe o progresso com onProgress. O método lança erros tipados que você pode capturar com instanceof:
| Erro | Quando |
|---|---|
InsufficientCreditsError, StorageExceededError, JobBlockedError | A execução foi recusada antes de qualquer tarefa começar. |
ModelUnavailableError | Esta implantação não oferece o modelo, ou um administrador o desativou. Escolha outro modelo. |
JobFailedError | A tarefa terminou como failed ou cancelled. O erro traz o jobId e a mensagem de erro. |
JobTimeoutError | O tempo de maxMs passou. A tarefa não é cancelada e geralmente ainda termina: busque-a depois com client.jobs.get(jobId). |
JobAbortedError | O seu signal foi disparado. |
JobHeldError | A tarefa entrou em pending_review em uma implantação que revisa os resultados. A tarefa não é cancelada: verifique de novo mais tarde. |
Na CLI, passe corpos complexos, como arrays ou objetos aninhados, em um arquivo com --params-file body.json. Os valores das flags substituem os do arquivo para a mesma chave, e true, false, null e números são convertidos a partir do texto.
Configurações do nó Gerar imagem
Os campos abaixo são as configurações mais usadas de POST /v1/generate-image. Leia Gerar imagem para saber o que cada configuração faz no editor, e os modelos de imagem para saber o que cada modelo aceita.
Propriedade
Tipo
Uma edição com máscara ou um refinamento custa o mesmo que uma nova geração nesse modelo.
No GPT Image 2.6 Flare e no Sunburst, outputFormat grava um JPEG, um WebP, um GIF animado de 512×512 ou um desenho SVG em vez de um PNG. Um GIF ignora aspectRatio e resolution, e uma máscara com gif ou svg é recusada com 400. A tarefa concluída indica o tipo do arquivo em output_data.imageMimeType. Veja Correções de parâmetros para saber como as configurações de cada formato são corrigidas, e os formatos do Gerar imagem para os preços.
/v1/generate-image pode responder com warnings, uma lista de { code, message }, para algo que você pediu e que não foi enviado. Hoje o único código é moodboard_images_not_sent: algumas imagens de um painel de inspiração não couberam no limite de referências do modelo. A execução segue, e a tarefa guarda os mesmos avisos em input_data.warnings.
Aplicar uma predefinição
POST /v1/generate-image aceita presetId: um ID integrado, como generate-image/cinematic-still, ou o uuid de uma das suas próprias predefinições. Liste os IDs integrados com GET /v1/node-presets/factory?nodeType=generate-image, que não exige token. A rota aplica a predefinição do jeito que o editor a aplica a um nó Gerar imagem, então a tarefa é a mesma que o botão Executar do editor enviaria:
- O prompt da predefinição e o texto antes e depois dele (
promptPrefixepromptSuffix). - Os marcadores
{name || default}preenchidos com os padrões deles. - O
styledela, incorporado ao prompt. - O prompt negativo dela, enviado de forma nativa a um modelo que aceita um, e adicionado ao prompt como uma linha
Avoid:em todos os outros modelos. - As configurações dela, e os padrões do editor para as que ela deixa sem valor: o modelo
gpt-image-2e a proporção16:9. O modelo e o preço são os mesmos do editor.
Os campos que você envia substituem a predefinição, como uma edição no nó aplicado faria. O seu prompt substitui o da predefinição e é envolvido pelo texto antes e depois dela. provider, aspectRatio, resolution, quality, negativePrompt, style e as outras configurações substituem os valores da predefinição. As referências, sessionId e origin são mantidos.
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"presetId": "generate-image/logo-wordmark", "presetVariables": {"BRAND": "Acme"}}'- Um marcador sem padrão, como
{BRAND}, precisa do valor dele empresetVariables. Sem ele, a rota responde400comcode: "preset_variables_required"etokens: ["BRAND"]. - Um
presetIddesconhecido responde404 preset_not_found. - A verificação de créditos calcula o preço da requisição depois de aplicar a predefinição. Nem
presetIdnempresetVariablesficam guardados na tarefa. - Uma predefinição que trabalha a partir de fotos tem
minReferencesacima de 0. Envie essa quantidade de imagens emreferenceImageUrls. Veja Predefinições. - Uma predefinição se combina com
countemodels. Veja a próxima seção. - Uma predefinição não pode usar as suas próprias paletas ou painéis de inspiração. Quando a
directiondela indicapalette:<id>oumoodboard:<id>, enviada por você ou salva na predefinição, a rota responde400 validation_errorcomfieldindicando a chave. Isso acontece antes de qualquer criação ou cobrança.
Várias imagens em uma chamada
POST /v1/generate-image pode criar várias imagens de uma vez:
count(de 1 a 4) cria essa quantidade de imagens de um modelo. Cada imagem é uma tarefa própria.models(de 2 a 4 IDs distintos de modelos de imagem, os mesmos IDs queprovideraceita) substituiprovidere envia a mesma requisição a cada modelo. As configurações de cada modelo são ajustadas a ele como em uma chamada única, e as correções são informadas por modelo.- Com os dois,
countvale por modelo:models: ["gpt-image-2", "flux-2-max"]comcount: 2cria quatro imagens. Uma requisição cria no máximo 8 imagens.
curl -s -X POST https://app.nodaro.ai/v1/generate-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0f8e6c1a-try-1" \
-d '{"prompt": "a lighthouse at dusk", "models": ["gpt-image-2", "flux-2-max"], "count": 2, "seed": 41}'{
"jobId": "<first job>",
"jobIds": ["<job 1>", "<job 2>", "<job 3>", "<job 4>"],
"batchId": "6b1f7e2a-0c4d-5e8f-9a1b-2c3d4e5f6a7b",
"groups": [
{ "model": "gpt-image-2", "jobIds": ["<job 1>", "<job 2>"], "credits": <credits> },
{ "model": "flux-2-max", "jobIds": ["<job 3>", "<job 4>"], "credits": <credits>,
"adjustments": [{ "field": "resolution", "from": "1K", "to": "2 MP", "reason": "..." }] }
],
"totalCredits": <credits>
}Cada imagem é cobrada pelo que uma chamada única dela custa. Sem count e models, ou com count: 1, a resposta é o habitual { "jobId" }. jobId é sempre a primeira tarefa, então um código que o lê continua funcionando.
- Créditos: o lote inteiro ou nada. O saldo é verificado contra o total do lote antes de qualquer criação. Quando ele não basta, a rota responde
402 insufficient_creditscomrequiredigual ao total, e nada é criado. Quando uma cobrança falha no meio, as tarefas já criadas são reembolsadas e removidas antes da resposta. - Idempotência por imagem. Com
Idempotency-Key: K, a imagem i recebe a chaveK:i. Repetir a requisição com a mesma chave retorna os mesmos IDs de tarefa e nunca cobra uma tarefa duas vezes. Um lote criado só em parte é completado. Uma segunda requisição com a mesma chave ao mesmo tempo espera a primeira, ou responde409 batch_in_progressdepois de 15 segundos; tente de novo. Repetir uma chave com um corpo diferente, ou em outra rota, responde422 idempotency_key_reused. - Um lote que não pode entrar na fila. Se as tarefas não puderem entrar na fila para começar, elas são reembolsadas e removidas. A requisição então responde
500 internal_error, e uma nova tentativa com a mesma chave começa o lote de novo. Quando algumas tarefas começaram, o500as nomeia emerror.startedJobIds. Uma nova tentativa com a mesma chave retorna essas e começa só o restante. - Seeds. Com
seed, a imagem i de cada modelo recebeseed + i, então as imagens são diferentes. - Com uma predefinição,
countcria N imagens da requisição da predefinição. Commodels, a predefinição é aplicada uma vez por modelo, então cada modelo recebe a requisição que o editor montaria para ele. - Encontre um lote depois. Toda tarefa do lote traz o mesmo
input_data.batchIde a posição dela eminput_data.batchIndex.GET /v1/jobs?batchId=<id>lista as tarefas. - Recusado antes de qualquer criação com
400 validation_error:countfora de 1 a 4, menos de 2 ou mais de 4models, um modelo repetido ou desconhecido,modelsjunto comprovider, ou mais de 8 imagens. Um modelo que a implantação não oferece responde403 model_not_available.
Gerar uma máscara
POST /v1/generate-mask seleciona em uma imagem um objeto descrito em texto e retorna uma imagem de máscara em preto e branco. O branco é o objeto. O corpo é { imageUrl, prompt, threshold? }:
promptaceita de 1 a 500 caracteres, por exemplo"the person".thresholdvai de 0 a 1, com padrão 0,3. Um valor menor seleciona mais.
Um corpo malformado é um 400 validation_error. A resposta é { jobId }. A saída da tarefa concluída é { maskUrl, imageUrl }: maskUrl é o PNG da máscara, e imageUrl é a imagem de origem, repassada sem mudanças. Passe as duas para uma edição de inpainting. Uma execução custa 55 créditos, e GET /v1/credits/model-cost?model=generate-mask responde o mesmo preço. Veja Gerar máscara.
Dividir uma imagem em camadas
POST /v1/split-into-layers transforma uma imagem em uma imagem base e camadas separadas, cada elemento no próprio PNG transparente. O corpo é { imageUrl, maxLayers?, size?, prompt?, sessionId?, origin? }:
imageUrlé uma URL http(s).maxLayersvai de 1 a 99, com padrão 9. Uma imagem com mais elementos tem os elementos juntados em menos camadas, e nenhum é descartado.sizeé"1K"(padrão),"1.5K","2K"ou"auto": a quantidade de pixels de cada imagem. 1K é cerca de um megapixel, e"auto"mantém o tamanho da própria imagem, entre 1K e 2K.promptaceita até 2.000 caracteres: o que separar. Ele pode trazer marcas<bbox>x1 y1 x2 y2</bbox>, de 0 a 1000, para indicar uma área. Em branco, os elementos principais são encontrados automaticamente.sessionIdeoriginfuncionam como em toda rota que cria tarefas. Um cabeçalhoIdempotency-Keyopcional faz uma nova tentativa com a mesma chave responder{ jobId, deduped: true }para a tarefa que ela já iniciou.
Um corpo malformado é um 400 validation_error antes de qualquer crédito ser reservado. A resposta é { jobId }. A saída da tarefa concluída é { imageUrl, layers, layerData, layerCount, layersNotSaved, libraryImages }:
imageUrlé a imagem base, um PNG opaco, elayerslista o arquivo de cada camada, de baixo para cima.layerDatatraz um{ name?, description?, zIndex, width?, height?, box?, boxNormalized?, url, baseUrl }por camada, na mesma ordem.zIndexé a ordem de empilhamento: 1 fica logo acima da base, e um número maior é desenhado por cima.box({ x1, y1, x2, y2 }, canto superior esquerdo e canto inferior direito) é onde a camada fica na base, em pixels da base.boxNormalizedé a mesma caixa em uma escala de 0 a 1000.widtheheightsão os pixels do próprio arquivo da camada. Uma camada é recortada no próprio elemento, então redimensione-a para aboxdela para colocá-la de volta no lugar.
Uma execução reserva o preço do máximo de imagens que pode retornar, maxLayers + 1 com a base, no tamanho dela. Ela é cobrada só pelas imagens que retornar. 1K e 1.5K têm o mesmo preço, e 2K e auto também. Uma execução que não encontra nenhum elemento termina só com a base, pelo preço de uma imagem. Uma camada que não pôde ser salva fica de fora, é contada em layersNotSaved e não é cobrada. O POST /v1/quote informa a reserva de uma execução antes de ela começar: veja Cotações de execução. Veja também Dividir em camadas.
Gerar um vídeo
Duas rotas geram vídeo. POST /v1/generate-video anima a partir de imagens: um quadro inicial em imageUrl, um quadro final opcional em endFrameUrl, ou só referências, nos modelos que as aceitam. POST /v1/text-to-video gera um clipe só a partir de um prompt, então o prompt dela é obrigatório. Quando você omite provider, a rota usa o modelo de vídeo padrão da plataforma.
POST /v1/text-to-video também aceita um booleano opcional contentPolicyRewrite. Quando ele está ausente ou é true, uma recusa por direitos autorais é tentada de novo uma vez com um prompt reescrito, e a saída da tarefa então traz contentPolicyRewrite: { original, rewritten }. Com false, uma recusa por direitos autorais faz a tarefa falhar.
{
"imageUrl": "https://…/frame.png",
"provider": "seedance-2",
"prompt": "she turns toward the window",
"duration": 8,
"resolution": "720p",
"direction": { "cameraMotion": "dolly-in", "timeOfDay": "dawn" }
}A resposta é { "jobId": "…" }, com warnings e adjustments quando se aplicam. A tarefa concluída traz output_data.videoUrl.
Propriedade
Tipo
Algumas regras mudam conforme o modelo:
- Na família Seedance 2,
resolutioneaspectRatiosão repassados como estão: um valor que o modelo não aceita é ignorado, nunca recusado. O Seedance 2 é o único com4keadaptive. O Seedance 2.5 gera até 30 segundos em uma chamada e, com um quadro inicial, sempre renderiza na proporção desse quadro. - Seedance 2.5 Flash (
seedance-2-5-flash) é o Seedance 2.5 mais rápido e mais barato. Ele também faz até 30 segundos em uma chamada, em480pou720p(o padrão). Uma requisição em1080prenderiza e é cobrada em 720p. Ele aceita até 10 imagens, 5 vídeos e 5 clipes de áudio de referência. Mais que isso responde400 too_many_references, com o limite, antes de qualquer reserva. Uma execução no editor ou em um workflow envia os primeiros em vez disso. Cada clipe de áudio de referência precisa ter de 2 a 30 segundos, e todos juntos no máximo 30 segundos. Um clipe que não é WAV nem MP3 é convertido para MP3 antes do envio, e um prompt só com áudio de referência é uma requisição válida. Um quadro inicial e oreferenceTaskTypefuncionam como no Seedance 2.5. Ele não temdraft, que é ignorado, e não aceitaseed. EmPOST /v1/video-to-video, ele é um modelo de edição ao lado doseedance-2-5. - O MiniMax H3 aceita
resolution2Kou768P, escritos exatamente assim.GET /v1/nodes/:typelista o valor a enviar emproviderResolutionWire. - Quadros e referências podem ser combinados no Seedance 2 e no MiniMax H3. Quando você envia uma referência junto com um quadro inicial ou final, os quadros viram referências numeradas no prompt, em vez de pontos fixos de início e fim. O Wan 3.0 não consegue enviar os dois, então o quadro é adicionado ao final da lista de referências, e a chamada continua sendo bem-sucedida.
- Vídeos de referência custam mais. Nos modelos que os cobram, um clipe de referência é precificado pela própria duração mais a duração da saída, então um clipe de origem mais longo reserva mais créditos. O Wan 3.0 cobra apenas os segundos de saída. O Kling 4.0 e o Kling 4.0 Flash cobram a saída mais o maior valor entre a saída e os clipes, então um clipe mais curto que a saída conta como a duração da saída.
characterReferencesmantém o rosto de uma pessoa real no Gemini Omni e no Gemini Omni Flash. Cada entrada é{ imageUrl, description, bodyImageUrl?, name?, voice? }: um retrato, uma descrição da pessoa com até 2.000 caracteres, uma imagem de corpo inteiro opcional e um nome opcional com até 100 caracteres.referenceImageUrlsé um contexto solto para o modelo, enquanto esta entrada segura o rosto. O Gemini Omni Flash 1.2 aceita até 2. Qualquer outro modelo responde400 character_references_unsupported. Um quadro inicial ou um quadro final na mesma requisição responde400 character_references_with_start_frameou400 character_references_with_end_frame, porque os modelos Gemini Omni não combinam personagens com um quadro. No Gemini Omni e no Gemini Omni Flash, a requisição precisa caber no orçamento de entrada do modelo, de 7 unidades: cada imagem conta 1, cada vídeo 2 e cada personagem 1, ou 2 com umbodyImageUrl. Uma requisição acima do orçamento responde400 character_references_quota. No Gemini Omni Flash 1.2, os personagens não contam em nenhum orçamento, e umvoiceresponde400 character_voice_unsupported. As referências de personagem não somam créditos.- Kling 4.0 (
kling-4) gera a partir só do texto ou de materiais de referência, com no máximo 15 no total. Ele aceitareferenceImageUrls(até 10),referenceVideoUrls(até 5, cada um de 2 a 30 segundos; um 6º responde400 reference_videos_over_limit),characterReferences(até 7) ereferenceAudioUrls(até 3). Mais que isso responde400antes de qualquer reserva:character_references_quotaquando a requisição trazcharacterReferences, evalidation_errornos outros casos. UmimageUrlouendFrameUrlconta como imagem: ele entra nas imagens de referência depois das suas, nomeado no prompt como o quadro de abertura ou de fechamento. Cada referência de personagem é um sujeito nomeado:imageUrl,bodyImageUrle até 3extraImageUrlssão as suas 2 a 4 imagens, e o prompt o chama de@<name>. Uma entrada com uma só imagem é enviada como uma imagem de referência comum. Um quadro inicial ou final é permitido com ela, e umvoiceresponde400 character_voice_unsupported; envie os clipes de voz comoreferenceAudioUrls. No prompt, nomeie os materiais como@image_N,@video_N,@<name>e@audio_N. Uma menção a um material que a requisição não traz perde o@, então a execução começa mesmo assim. Uma execução com vídeo de referência é cobrada por segundo da saída mais o maior valor entre a saída e os vídeos de referência, pela tarifa de referência. - Trilha sonora de áudio do Kling 4.0 (ativada por padrão). O primeiro clipe de
referenceAudioUrlstoca como a trilha sonora do resultado. Ele é enviado como mais um vídeo de referência: um quadro fixo que carrega o áudio, com a duração do áudio, no mínimo 2 segundos e no máximo a duração da saída. O som dele é mantido, então as pessoas atuam no ritmo exato da faixa. Os clipes seguintes continuam vozes nomeadas, e@audio_2vira@Voice1. A trilha sonora ocupa uma das 5 vagas de vídeo de referência, e a execução é cobrada como uma execução com vídeo de referência.audioSoundtrack: falsemantém todos os clipes como amostras de voz. Com a trilha sonora, o Kling também mantém o som dos vídeos de referência que você enviar. - Kling 4.0 Keyframes (
kling-4-keyframes) aceita um quadro inicialimageUrl, até 8 quadros intermediários comoreferenceImageUrls, em ordem, e umendFrameUrl. Um quadro final sozinho é permitido, e nenhum quadro é texto para vídeo. O total de quadros é limitado peladuration: 4 com 3 segundos, um a mais a cada segundo, e 10 a partir de 9 segundos. Mais que isso, ou mais de 8 quadros intermediários, responde400 validation_errorantes de qualquer reserva. No prompt, os quadros são@first_frame,@keyframe_Ne@last_frame, e@image_Né reescrito como@keyframe_N.aspectRatiosó vale sem nenhum quadro. Ele não aceita vídeos de referência, áudio nem personagens. - Os dois modelos Kling 4.0 aceitam uma
durationde 3 a 30 segundos inteiros (padrão 5) e umaresolutionde720p(padrão) ou1080p; qualquer outra resolução renderiza e cobra 720p.aspectRatioéauto(padrão: segue os materiais, e 16:9 sem nenhum),16:9,9:16,1:1ou21:9. O som está sempre ativado (soundé ignorado), não háseed, e o prompt pode ter até 8.000 caracteres. Eles são cobrados por segundo e não estão disponíveis no plano gratuito. - O Kling 4.0 Flash (
kling-4-flash) escolhe o modo pelo que você envia. UmimageUrlsemreferenceImageUrls,referenceVideoUrlsnemcharacterReferencesé o quadro de abertura exato. Nesse caso,aspectRationão é usado, e o prompt chama o quadro de@first_frame. Qualquer outra coisa roda no modo de referência: só um prompt, referências, personagens ou um quadro inicial junto com eles. No modo de referência, umimageUrlentra nas imagens de referência depois das suas, como nokling-4. - Referências do Kling 4.0 Flash. O modo de referência aceita
referenceImageUrls(até 10),referenceVideoUrls(até 5, de 2 a 20 segundos somados) echaracterReferences(até 7 sujeitos nomeados, como nokling-4), com no máximo 15 materiais no total. Um conjunto de vídeos de referência fora de 2 a 20 segundos, ou um 6º vídeo, responde400antes de qualquer reserva. Não há vozes separadas: o clipe N dereferenceAudioUrls(até 7) vira a voz da entrada N decharacterReferences, em ordem. Um personagem precisa de 2 a 4 imagens, ou de umvideoUrl, para carregar uma voz. Um clipe cujo personagem tem uma só imagem e nenhum vídeo, e qualquer clipe depois do último personagem, é descartado, e a execução começa mesmo assim. Um clipe não ocupa vaga de material, e uma menção@audio_Nperde o@.keepOriginalSoundfunciona como nokling-4. Não háaudioSoundtrack. - Configurações do Kling 4.0 Flash.
durationvai de 3 a 20 segundos (padrão 5). O modelo renderiza só em 720p: qualquerresolutionrenderiza e cobra 720p.aspectRatioé como nokling-4, o som está sempre ativado, não háseed, e o prompt pode ter até 8.000 caracteres. Não há quadro final: umendFrameUrljunto com umimageUrlou com referências não é enviado ao modelo. UmendFrameUrlsozinho emPOST /v1/generate-videoresponde400(imageUrl is required). Ele é cobrado por segundo, com uma única tarifa para os dois modos. Uma execução com vídeo de referência cobra a saída mais o maior valor entre a saída e os vídeos de referência, pela tarifa de referência. Ao contrário dos outros modelos Kling, ele roda com créditos gratuitos, como um clipe de 3 ou 4 segundos. - PixVerse V6 Max (
pixverse-v6-max) é um id para dois modos. NoPOST /v1/generate-video, oimageUrlé o quadro inicial exato, e o clipe assume o formato dele. NoPOST /v1/text-to-video,aspectRatioé16:9(padrão),4:3,1:1,3:4,9:16,2:3,3:2ou21:9; outra proporção vai para a mais próxima delas.durationvai de 1 a 15 segundos (padrão 5).resolutioné360p,540p,720p(padrão) ou1080p, e qualquer outro valor renderiza e cobra 720p.seedé um número inteiro de 0 a 2147483647, e o prompt pode ter até 5.000 caracteres. - Som no PixVerse V6 Max. O áudio nativo fica ligado, a menos que você envie
sound: false. Semsound,generateAudio: falsetambém o desliga, esoundvale quando os dois são enviados. O som muda o preço: cada duração e resolução tem um preço sem som e um preço com áudio. Não há quadro final, nem imagens, vídeos ou áudios de referência: eles não são enviados ao modelo. Ele roda com créditos gratuitos em 360p, de 1 a 4 segundos. - Grok Imagine 1.5 (
grok-imagine-video-1.5) precisa de umimageUrl, o quadro inicial exato. UmendFrameUrlé o quadro final exato, e a mesma URL nos dois faz um loop sem emenda. Até 4 quadros intermediários vão emreferenceImageUrls, em ordem. Eles caem em segundos inteiros espalhados de forma uniforme pelo clipe, então dois quadros em um clipe de 8 segundos caem em 3 e 5 segundos. - Limites do Grok Imagine 1.5. Um clipe de D segundos aceita no máximo D − 1 quadros intermediários, e os quadros a mais ficam de fora, nunca são recusados. Quadros intermediários ou um
endFrameUrlsemimageUrlrespondem400 image_required.durationvai de 1 a 15 segundos (padrão 8).resolutioné480p(padrão),720pou1080p, e qualquer outro valor renderiza e cobra 480p. Não háseed, nem vídeos, áudios ou personagens de referência. O preço é por segundo, conforme a resolução, e os quadros não acrescentam nada. - Em 1080p, o Grok Imagine 1.5 aceita só o quadro inicial. Uma execução em 1080p que também envia quadro final, loop ou quadros intermediários responde
400 start_frame_only_resolutionantes de reservar créditos. Escolha 720p, ou remova os outros quadros. Em 480p e 720p, todos os quadros são aceitos. - Personagens em vídeo no Kling 4.0 e no Kling 4.0 Flash. O
videoUrlopcional de uma entrada decharacterReferencesé um clipe de 3 a 8 segundos em uma só tomada do personagem. Ele faz da entrada um sujeito criado a partir desse vídeo em vez das imagens.imageUrledescriptioncontinuam obrigatórios. O clipe entra nos vídeos de referência da execução, então é medido e limitado como um deles. Uma requisição aceita no máximo 3 entradas desse tipo e no máximo 5 vídeos comreferenceVideoUrls. Todos os vídeos somados precisam caber em 30 segundos no Kling 4.0 e em 20 segundos no Flash, e duas entradas não podem compartilhar um clipe. O preço é o de uma entrada só com imagens, então ele não acrescenta nada. Uma requisição fora desses limites responde400antes de qualquer reserva:character_videos_over_limit,reference_videos_over_limit,character_video_shared, ouvideo_too_longpara um clipe fora de 3 a 8 segundos. Um clipe ilegível responde400 character_video_unreadable. Qualquer outro modelo responde400 character_video_unsupported. Veja Personagens em vídeo. voicefixa uma voz em uma referência de personagem entre clipes:{ preset, description?, exampleLine? }, em quepreseté um dos IDs de voz do Gemini. Uma requisição pode fixar até 3 vozes diferentes, ou responde400 character_voices_over_limit. Veja Gerar vídeo para as vozes.
Para as durações, as resoluções e os preços em créditos de cada modelo, leia os modelos de vídeo ou chame GET /v1/models.
Tipo de tarefa de referência do Seedance 2.5
POST /v1/generate-video e POST /v1/text-to-video aceitam um referenceTaskType opcional. Ele diz ao Seedance 2.5 para que serve a mídia de referência (referenceImageUrls, referenceVideoUrls e referenceAudioUrls), em vez de deixar o modelo adivinhar pelo prompt.
| Valor | O que faz |
|---|---|
auto | O padrão, também quando o campo não vem. Nada é declarado, e o modelo decide pelo prompt. |
reference | A mídia só guia um clipe novo. A solicitação mantém a proporção e a duração com que foi enviada. |
edit | O clipe é uma edição do vídeo de referência, no formato e na duração do próprio vídeo: aspectRatio vira adaptive e duration vira automática (-1). Precisa de pelo menos um vídeo de referência, e todos os vídeos de referência precisam ter de 4 a 30 segundos, como a plataforma os mede. Caso contrário, nada é declarado, e a solicitação mantém a proporção e a duração. |
extend | O clipe continua o vídeo de referência, no formato do próprio vídeo (aspectRatio vira adaptive). Uma duration automática ou ausente vira a duração padrão do modelo, defaultDuration no GET /v1/models. Você recebe só a continuação, não o clipe de origem emendado nela. Para os dois em um só vídeo, use Estender vídeo. Precisa de pelo menos um vídeo de referência. |
-
Ignorado, nunca um erro, em qualquer outro modelo e em uma solicitação sem mídia de referência. Um quadro inicial ou final não é mídia de referência. Um valor diferente dos quatro acima é um
400 validation_error. Os modelos que aceitam o campo listam os valores dele emreferenceTaskTypesnoGET /v1/models. -
O que ele muda é informado. Uma proporção ou duração que
editouextendsubstitui volta emadjustmentse, no/v1/generate-video, também emwarnings. Uma proporção automática não é substituída, porque com um vídeo de referência ela já roda emadaptive. -
O preço segue os valores com que a execução roda. A execução é cotada, reservada e enviada com esses valores. O
POST /v1/quotecom o mesmo corpo calcula o preço do mesmo jeito. Uma execuçãoreferencecom duração automática é reservada na saída mais longa que o modelo consegue fazer, e cobrada pelo que fizer. -
Um rascunho também declara. Uma solicitação com
draft: truedeclara o tipo exatamente como a mesma solicitação semdraft, em 480p. A finalização em 1080p de um rascunhoeditrenderiza de novo a mesma edição, na duração do clipe de origem. -
Uma declaração descartada não é informada. Uma solicitação que pediu um tipo e não o recebeu, por exemplo sem vídeo de referência, responde como qualquer outra. O
input_data.referenceTaskTypeda tarefa só é preenchido quando um tipo foi declarado. -
POST /v1/video-to-videocomprovider: "seedance-2-5"sempre pedeedit, seja qual for o corpo. A edição é declarada quando todos os clipes, ovideoUrlde origem e osreferenceVideoUrls, têm de 4 a 30 segundos. Caso contrário, ela vai sem declaração, e o modelo lê o prompt. -
Gravado em um nó de workflow, ele só é mantido onde um modelo o aceita. Toda gravação de um workflow verifica esse campo nos nós Gerar vídeo, Imagem para vídeo, Texto para vídeo e Vídeo para vídeo. O valor só é mantido enquanto um modelo que o nó executa o lista. Caso contrário, a chave é removida, e nada mais no nó muda.
autotambém é removido. Isso vale paraPOST /v1/workflows,PATCH /v1/workflows/:idePOST /v1/workflows/import. Vale também para os salvamentos do editor e para o instantâneo publicado de um app ou de um template. As gravações do MCP e as edições do Copilot informam a remoção.
No MCP, o campo é reference_task_type em generate_video.
Usar referências
Referências são imagens (e, no vídeo, também clipes e áudio) que o modelo deve seguir. Você pode enviá-las como uma lista simples de URLs ou como referências estruturadas, que a rota numera, rotula e escreve no prompt por você, exatamente como o editor faz com os nós conectados.
Referências estruturadas
POST /v1/generate-image, POST /v1/generate-video, POST /v1/text-to-video e POST /v1/extend-video aceitam connectedReferences. Cada entrada descreve uma imagem:
Propriedade
Tipo
Nas rotas de vídeo, a rota transforma essas entradas em referências numeradas:
- Toda referência que você não menciona é anexada. A URL dela entra na lista de referências, sem duplicatas, e ganha uma linha como
@image_1 (reference): <label>. Já uma entradawired-characterpassa a fazer parte de uma instrução “Use these characters:” (use estes personagens:). - A lista é cortada no limite do modelo antes da numeração, então um número de referência no prompt nunca aponta para uma imagem que não foi enviada.
{image:N:label}no prompt vira “the label from@image_N”, numerado em relação às referências anexadas.{ref:<id>}e{ref:<id>:label}apontam para uma referência peloidque você deu a ela. A plataforma substitui o token pelo número da referência depois de numerar a lista, então você nunca calcula um número. A lista é numerada nesta ordem: primeiro a lista simplesreferenceImageUrls, depois os personagens que você não mencionou, depois as outras entradas, na sua ordem. Um token cuja referência não foi anexada, por ter passado do limite ou porque o modelo não aceita referências, vira o rótulo dele; sem rótulo, viradefaultName; sem nenhum dos dois, não vira nada. Ele nunca chega ao modelo como texto bruto.referenceOrder, uma lista de IDs de referências, reordena as referências e as renumera de acordo.POST /v1/generate-imagetambém aceita esse campo.
As cópias de exibição são substituídas pelos originais. Isso vale para toda entrada de imagem em POST /v1/generate-video e POST /v1/text-to-video: imageUrl, endFrameUrl, referenceImageUrls e referências conectadas ou de personagem. Uma entrada que é uma cópia de exibição redimensionada de uma imagem do CDN do Nodaro, https://cdn.nodaro.ai/cdn-cgi/image/<options>/<path>, é registrada e enviada como o arquivo original, https://cdn.nodaro.ai/<path>. O mesmo vale para as imagens de uma execução de trend e de uma execução do Video Remake. URLs de outros hosts são usadas como foram enviadas.
Os metadados embutidos são removidos antes que um modelo veja uma imagem. Algumas imagens de entrada trazem dados embutidos, como Content Credentials, EXIF, XMP, IPTC ou blocos de texto PNG. Uma imagem assim é recodificada sem esses dados, no próprio formato, antes de ser enviada ao modelo. Uma imagem limpa é enviada como está. O seu arquivo armazenado não muda.
connectedReferences só envia imagens. referenceVideoUrls e referenceAudioUrls continuam sendo listas simples. Se você omitir connectedReferences, as rotas se comportam como antes: o seu prompt e as suas referenceImageUrls são enviados como estão.
Em POST /v1/generate-image e na ferramenta generate_image do MCP, um token {image:N} ou {image:N:label} no prompt aponta para a N-ésima imagem de referência:
- Sem referências conectadas, N conta as
referenceImageUrlssimples, na ordem, então{image:1}é a primeira URL que você enviou. Isso inclui uma requisição cujas únicas outras referências sãodescribedReferences. - Com pelo menos uma entrada em
connectedReferences, N conta as entradas deconnectedReferences, na ordem. AsreferenceImageUrlssimples da mesma requisição continuam anexadas, antes das conectadas, mas nenhum token aponta para elas. Para citar uma foto no prompt, envie-a como uma entrada deconnectedReferences. - Um token sem imagem na posição dele vira o rótulo dele:
{image:2:person}é lido comoperson. Um{image:2}sem rótulo é omitido.
Modelos com um limite de imagens próprio recusam imagens a mais. O Seedream 5.5 e o FLUX 3 Klein aceitam no máximo 10 imagens de entrada. O GPT Image 2.6 Flare, o GPT Image 2.6 Sunburst e o MiniMax H3 Image aceitam no máximo 16. Uma imagem base conta para o limite. Uma requisição que enviaria mais é recusada com 400 validation_error antes de qualquer cobrança, e a mensagem diz quantas remover. As referenceImageUrls simples, as connectedReferences e a base contam. Nesses modelos, connectedReferences e referenceOrder aceitam até 16 entradas, como referenceImageUrls. O que decide é o número de imagens que a requisição enviaria, e entradas que compartilham uma imagem contam uma vez. Por exemplo, 15 menções a 10 imagens diferentes rodam no Seedream 5.5. Em todos os outros modelos, connectedReferences e referenceOrder mantêm o limite de 14 entradas. Uma requisição que não indica modelo segue o limite do modelo em que roda, o padrão para a proporção dela. O POST /v1/image-to-image responde do mesmo jeito, contando o imageUrl dele. Uma execução de workflow no Seedream 5.5, no GPT Image 2.6 ou no MiniMax H3 Image ainda envia as primeiras 10 ou 16 imagens e deixa o restante de fora; o FLUX 3 Klein recusa ali também.
O editor e uma execução de workflow numeram os tokens do mesmo jeito. Uma imagem que chega a um nó Gerar imagem passando por um nó intermediário, como um nó Texto, também é enviada e numerada.
Quais modelos de vídeo aceitam imagens de referência
| Família de modelos | Imagens de referência |
|---|---|
| Família Seedance 2 | Até 9 |
| HappyHorse Ref2V | Até 9 |
| Gemini Omni, Kling 3 Omni, Grok Imagine image-to-video | Até 7 |
| VEO 3.1 Fast e VEO 3.1 Lite | Até 3 |
Em qualquer outro modelo, os tokens {image:N} são reduzidos aos rótulos e nada é anexado. O VEO 3.1 Quality não está na lista: as referências enviadas com veo3 são ignoradas, e a execução usa os quadros dela.
Vídeo só com referências
Em POST /v1/generate-video, o quadro inicial é opcional quando o modelo aceita pelo menos um dos tipos de referência que você envia, por exemplo o Kling 3 Omni só com referenceImageUrls. Uma execução só com referências no VEO 3.1 Fast ou no Lite muda sozinha para o modo de referência, então você não precisa de generationType. Um tipo de referência que o modelo não consegue usar não conta: referências só de áudio em um modelo que aceita apenas imagens são recusadas com 400.
Um quadro final sozinho é aceito nos modelos que o incorporam às referências: a família Seedance 2, o MiniMax H3 e o Wan 3.0. Envie endFrameUrl uma vez, sem repetir a imagem em referenceImageUrls. O pacote @nodaro/shared exporta videoProviderFoldsLoneEndFrame(provider) para que a sua interface use a mesma regra.
Quando uma requisição não tem quadro inicial, nem modo de referência, nem uma referência que o modelo possa usar, a resposta depende do modelo:
- Um modelo que não consegue gerar vídeo só a partir de texto, como o Kling 3 Omni, o HappyHorse Ref2V ou o Hailuo 2.3, retorna
400 image_required. A mensagem diz se referências funcionariam no lugar.GET /v1/modelsé a fonte oficial sobre quais são esses modelos. - Todos os outros modelos retornam
400 validation_errore indicamPOST /v1/text-to-videopara um clipe só com prompt.
Alguns modelos têm um id para texto para vídeo e outro para imagem para vídeo: Grok Imagine (grok e grok-i2v), Wan (wan e wan-i2v), Wan 2.7 (wan-2.7-t2v e wan-2.7-i2v) e HappyHorse (happyhorse e happyhorse-i2v). POST /v1/generate-video é a rota de imagem para vídeo. Uma requisição nela que indica o id de texto para vídeo, com um imageUrl ou imagens de referência, é executada como o id de imagem para vídeo. Ela é cobrada, registrada na tarefa e enviada com esse id, e POST /v1/quote faz o orçamento do mesmo jeito. Uma requisição só com prompt que indica qualquer um dos ids recebe o 400 validation_error acima. Em POST /v1/text-to-video, indique o id de texto para vídeo: um id de imagem para vídeo ali é um 400 validation_error. As duas recusas acontecem antes de qualquer reserva.
Estender vídeo
POST /v1/extend-video só aceita connectedReferences e referenceImageUrls com provider: "seedance-2-5-extend" (Seedance 2.5), "seedance-2-5-flash-extend" (Seedance 2.5 Flash) ou "seedance-2-0-extend" (Seedance 2.0). Uma requisição mais antiga que indica seedance-2-extend roda como Seedance 2.5. Qualquer outro modelo de extensão recusa referências com 400. O limite, em cada um, é de 8 imagens suas, porque o último quadro do clipe de origem ocupa uma vaga de referência, depois das suas, e assim os seus números nunca mudam. O final da origem vai como @video_1: os últimos 10 segundos no Seedance 2.5, e os últimos 2 segundos no Seedance 2.0. O Seedance 2.5 e o Seedance 2.5 Flash não enviam uma âncora de último quadro e mantêm o mesmo limite de 8 imagens. No Seedance 2.5 Flash, uma origem com menos de 2 segundos não pode ser estendida. Imagens de referência não adicionam créditos. O nó Estender vídeo não tem direction nem subject, porque o prompt dele continua um clipe que já tem um visual.
Referências descritas
describedReferences nomeia um assunto que você consegue descrever, mas do qual ainda não tem imagem, como um papel em um roteiro. POST /v1/generate-image, /v1/generate-video, /v1/text-to-video e /v1/extend-video aceitam até 10 entradas { name, description }. O nome pode ter até 80 caracteres, e a descrição, até 2.000.
- Nada é anexado. Uma referência descrita não ocupa vaga de referência, e a numeração das suas outras referências não muda.
- Ela chega ao modelo como uma linha de texto:
<Name> — <description>.Mantenha o nome no seu prompt, por exemploNatalie walks down the pier., e a linha diz ao modelo quem é Natalie. Não escreva uma menção com@para ela: essa sintaxe aponta para uma imagem anexada. - Ela funciona sozinha. Envie
describedReferencessem nenhumaconnectedReferences, o caso comum de uma história escrita antes de existir qualquer personagem. - Entradas sem nome ou sem descrição são descartadas, e um nome repetido é escrito uma vez só. Todos os modelos de extensão aceitam referências descritas, porque elas não trazem URL.
Descrições e legendas por uso
descriptionOverride, em uma entrada deconnectedReferences, diz o que a referência é só nesta execução, em até 2.000 caracteres. Ele preenche a descrição que a instrução da referência já tem, com prioridade sobre a descrição salva. Quando a instrução não tem descrição, ele adiciona uma linha, então o modelo recebe a informação uma vez, nunca duas.referenceVideoCaptionsereferenceAudioCaptions, emPOST /v1/generate-videoe/v1/text-to-video, descrevem os clipes e os áudios de referência, com até 500 caracteres cada. Eles são alinhados por índice:referenceVideoCaptions[0]descrevereferenceVideoUrls[0]. Cada um vira uma linha como@video_1: <caption>., e uma entrada vazia pula um clipe sem quebrar o alinhamento.
Mencionar uma referência no prompt
Em POST /v1/generate-image, você pode colocar uma referência dentro da sua frase, em vez de deixá-la na lista do final. Escreva @<name-slug>:<index>, ou @<name-slug>:<index>:<role> para dizer o que aproveitar dela:
{
"prompt": "a wide shot of @nessie:1 rising beside @dock:2:material",
"connectedReferences": [
{ "id": "cr-1", "defaultName": "Nessie", "source": "wired-creature", "url": "https://…/nessie.png" },
{ "id": "ob-1", "defaultName": "Dock", "source": "wired-object", "url": "https://…/dock.png" }
]
}O modelo recebe “a wide shot of the creature from reference image A rising beside the material from reference image B” (um plano geral da criatura da imagem A surgindo ao lado do material da imagem B).
- O slug vem de
defaultName, em minúsculas, com cada sequência de outros caracteres trocada por um único-:Old Townviraold-town. Não existe campo de slug para definir. - O índice só associa a menção a uma referência. Ele nunca é escrito no prompt, e a própria plataforma numera as referências.
- Os papéis para imagens (
manualewired-image) sãoobject,person,face,clothes,background,style,poseetexture. Criaturas aceitamcreature,anatomy,markings,pose,colorestyle. Objetos aceitamobject,shape,material,color,textureestyle. Qualquer outra palavra única passa como foi escrita. Sem papel, vale odefaultRoleda entrada. ~locke~nolockdepois de uma menção, como em@town:1:background~lock, ativam ou desativam o bloqueio de identidade dessa referência para a menção.- Os nomes são resolvidos nesta ordem: personagem, local, imagem, criatura, objeto. Um nome compartilhado por um personagem e uma imagem indica o personagem, e, dentro de um mesmo tipo, vale a primeira correspondência.
- Um nome cujo slug começa com um dígito não pode ser mencionado, por exemplo
3D Render, que vira3d-render. Renomeie a referência para mencioná-la. Uma menção a uma referência que passou do limite do modelo fica como texto literal. - Mencionar uma referência a move da lista do final para o lugar onde você a digitou, e as letras das referências seguintes mudam para acompanhar a frase. Para uma criatura ou um objeto, a menção também substitui a linha que, sem ela, seria adicionada no final.
Bloqueio de referência
referenceLock, em POST /v1/generate-image, adiciona antes da cena a redação testada do Nodaro para fidelidade às referências:
| Valor | Adiciona | Use para |
|---|---|---|
standard | Instruções para usar só o que as referências mostram, manter a semelhança e compor as referências juntas | Composições a partir de várias referências |
multi-person | O mesmo, mais regras para nunca alterar nem misturar rostos | Dois ou mais rostos em uma tomada |
Você envia o ID, não o texto: a redação pertence à plataforma e melhora sem que você atualize o cliente. Se você omitir o campo, nenhum bloqueio é adicionado.
Direção cinematográfica por ID
direction descreve a câmera, a luz e o visual com IDs de seletores, em vez de texto corrido. POST /v1/generate-image, POST /v1/generate-video e POST /v1/text-to-video aceitam o campo. O Nodaro escreve no prompt a própria redação testada para cada ID, então uma requisição salva incorpora as melhorias de redação com o tempo, em vez de congelar o texto que o seu cliente escreveu.
{
"prompt": "a knight on a hill",
"provider": "nano-banana-pro",
"direction": {
"shotSize": "wide-shot",
"lens": "wide-24mm",
"lightingStyle": "rembrandt",
"style": "anime",
"mood": ["happy", "joyful"]
}
}Chaves e a origem dos IDs
Cada chave é um campo de um seletor de Controles criativos. Obtenha os IDs válidos em GET /v1/picker-catalogs/<picker>, os mesmos catálogos que os seletores do editor usam.
| Chaves | Seletor | Imagem | Vídeo |
|---|---|---|---|
shotSize, angle, coverage, composition, vantage | Enquadramento | Sim | Sim |
pose | Pose | Sim | Sim |
compositionEffect | Efeitos de composição | Sim | Sim |
cameraFormat | Câmera / película | Sim | Sim |
lens | Lente | Sim | Sim |
aperture, shutterSpeed, isoValue | Configurações de exposição | Sim | Não |
timeOfDay, lightingStyle, lightingDirection, lightingRatio, colorTemperature | Iluminação | Sim | Sim |
colorLook | Cor / look | Sim | Sim |
atmosphere | Atmosfera | Sim | Sim |
postProcess | Efeitos de pós-produção | Sim | Não |
style | Estilo | Sim | Sim |
mood | Clima | Sim | Sim |
aesthetic | Estética | Sim | Sim |
photoGenre | Gênero fotográfico | Sim | Não |
photographer | Fotógrafo | Sim | Não |
renderQuality | Qualidade de renderização | Sim | Não |
setting | Cenário | Sim | Sim |
era | Época | Sim | Sim |
backdrop | Fundo de estúdio | Sim | Sim |
cameraMotion | Movimento de câmera | Não | Sim |
actionFx | Efeitos de ação | Não | Sim |
temporalSpeed, temporalFreeze, temporalDirection, temporalShutter | Efeitos temporais | Não | Sim |
transition | Transição | Não | Sim |
loopSubject | Tema de loop | Não | Sim |
Uma chave que não se aplica a uma rota é aceita e simplesmente não adiciona nada, então um mesmo mapa de IDs de visual pode ser enviado sem alterações às rotas de imagem e de vídeo.
Valores e limites
- Um ID ou uma lista. As chaves de escolha múltipla (
mood,aesthetic,photographer,atmosphere,postProcess,compositionelightingStyle) aceitam IDs até o limite de cada uma, e os IDs excedentes são descartados. Uma chave de escolha única que recebe uma lista usa a primeira entrada. - Dois limites resultam em recusa com
400 validation_error: mais de 8 entradas em uma chave e um ID com mais de 100 caracteres. - Ausente não é vazio. Uma chave ausente significa nenhuma indicação, nunca um valor padrão. Uma string vazia ou uma lista vazia não adiciona nada.
- As suas próprias paletas e painéis de inspiração nunca são ignorados.
colorLooktambém aceita"palette:<id>", estyleaceita"moodboard:<id>"em/v1/generate-image. Veja As suas próprias paletas e painéis de inspiração. - Chaves e IDs desconhecidos são ignorados, não recusados. Um cliente mais novo em um servidor mais antigo recebe menos indicações em vez de um erro, então atualize o servidor antes de um cliente que envia chaves novas.
- Pacotes de catálogo personalizados. Em uma implantação que registra os próprios pacotes de catálogo,
GET /v1/picker-catalogslista os IDs que um pacote adiciona. Esses IDs são aceitos, mas não adicionam redação adirection.
Onde entram as palavras
As cláusulas são adicionadas depois do seu prompt, em uma seção [style]. A linha de filme traz cameraFormat, colorLook, style e era, e a linha de cena traz as outras chaves de visual:
a knight on a hill
[style]:
<film line>
<scene line>- A ordem dentro de uma linha é a ordem fixa da plataforma, não a ordem das suas chaves. Uma cláusula repetida por duas chaves é escrita uma vez só.
- Uma linha vazia é omitida. Quando nenhuma chave adiciona nada, não há seção nenhuma, e o seu
promptchega ao modelo sem alterações. - Nas rotas de vídeo, as chaves de movimento funcionam de outro jeito. Elas adicionam um termo profissional curto, como
cross-dissolve, e ficam no corpo do prompt, depois do seu texto, porque o movimento faz parte da tomada.cameraMotionvem primeiro. Só as chaves de visual vão para a seção[style]. - Nas rotas de vídeo,
styleadiciona o texto de vídeo do estilo em vez do texto de imagem, na mesma seção[style]. O texto de vídeo é escrito para tomadas em movimento: ele cita primeiro o meio, depois as técnicas dele, e um estilo fotográfico cita um meio de ação ao vivo, para que continue fotografado. Por isso, o mesmo"style": "anime"é lido de forma diferente em uma rota de vídeo e em generate-image.jobs.input_data.promptregistra o texto que o modelo recebeu. Os endpoints de catálogo retornam apenas o texto de imagem. No canvas funciona do mesmo jeito: veja Estilos para imagens e para vídeo.
Quando o prompt é longo demais
Cada modelo aceita um prompt até um comprimento próprio. Um direction completo pode, sozinho, passar de um limite pequeno, por exemplo 3.000 caracteres no Seedream, do lado da imagem, e 1.000 caracteres no Kling, do lado do vídeo. Quando isso acontece, o Nodaro remove as cláusulas de direção uma de cada vez, a partir do final da sua ordem fixa, até o prompt caber. Nada mais é removido antes delas:
- As cláusulas de assunto só são removidas depois de todas as cláusulas de direção.
- O seu texto, as suas referências e as frases que as vinculam, as menções com
@e as linhasStyle:eAvoid:sempre ficam. - Só quando o prompt ainda não cabe, sem nenhuma indicação restante, o final do texto é cortado, com
...no fim.
Nas rotas de vídeo, o orçamento de caracteres também conta as instruções de referência que a rota adiciona, que nunca são removidas. Em um modelo sem configuração de prompt negativo, o seu negativePrompt é adicionado como uma linha Avoid: cujo espaço é reservado primeiro, então um prompt negativo longo custa cláusulas de indicação, não texto. O texto opcional de injectCharacterContext é adicionado depois dessa etapa e não entra no orçamento.
A tarefa registra o que aconteceu. input_data.prompt é o que o modelo recebeu, input_data.userPrompt é o texto que você enviou (uma string vazia quando você enviou só direction), e input_data.direction são os seus IDs, como foram enviados.
Direção salva em um nó
Um nó Gerar imagem em um workflow salvo pode guardar o mesmo objeto direction nos dados dele, escrito pela API, pelo MCP ou por um app que cria workflows. O editor respeita esse objeto em toda execução e na prévia do prompt final. Os IDs salvos se somam a qualquer seletor de Enquadramento, Iluminação ou Estilo conectado: a indicação do seletor conectado vem primeiro, depois os IDs salvos. As predefinições e as exportações de workflow mantêm os IDs junto com o resto do nó.
As suas próprias paletas e painéis de inspiração
Uma paleta é o seu próprio conjunto de 2 a 12 cores, e um painel de inspiração é o seu próprio conjunto de 1 a 12 imagens de referência com uma descrição. Salve-os uma vez e depois oriente qualquer execução de POST /v1/generate-image com um deles, do mesmo jeito que você escolhe um visual de cor ou um estilo integrado. Eles funcionam em todas as edições. Para saber o que fazem no editor, leia Paletas e painéis de inspiração.
| Uma paleta | Um painel de inspiração | |
|---|---|---|
| O que contém | Um nome de 1 a 80 caracteres, de 2 a 12 cores como #RRGGBB e uma observação opcional de até 500 caracteres | Um nome, uma descrição opcional de até 1.000 caracteres e de 1 a 12 imagens { url, caption? } |
| Como usar | direction.colorLook: "palette:<id>" | direction.style: "moodboard:<id>" |
| O que a execução recebe | Todas as cores no prompt, com um nome comum e o código hexadecimal | A descrição no prompt e as imagens como referências de estilo |
{
"prompt": "a lighthouse on a cliff at dusk",
"provider": "nano-banana-pro",
"referenceImageUrls": ["https://example.com/my-lighthouse.png"],
"direction": {
"colorLook": "palette:0f9e8d7c-6b5a-4c3d-9e2f-1a2b3c4d5e6f",
"style": "moodboard:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"lightingStyle": "rembrandt"
}
}Gerenciar paletas e painéis de inspiração
| Método | Caminho | Corpo ou parâmetros | O que faz |
|---|---|---|---|
GET | /v1/palettes | limit (de 1 a 100, padrão 50), cursor | As suas paletas, da mais nova para a mais antiga: { data, nextCursor }. |
POST | /v1/palettes | { name, colors, description? } | Cria uma paleta. Responde 201. As cores são guardadas em maiúsculas. |
GET | /v1/palettes/:id | Nenhum | Uma paleta. |
PATCH | /v1/palettes/:id | Qualquer um de name, colors, description | Só os campos que você envia são gravados. description: null limpa a observação. |
DELETE | /v1/palettes/:id | Nenhum | Retorna { success: true }. |
GET | /v1/moodboards | limit, cursor | Os seus painéis de inspiração, do mais novo para o mais antigo: { data, nextCursor }. |
POST | /v1/moodboards | { name, description?, images } | Cria um painel de inspiração. Responde 201. |
GET | /v1/moodboards/:id | Nenhum | Um painel de inspiração. |
PATCH | /v1/moodboards/:id | Qualquer um de name, description, images | Só os campos que você envia são gravados. images substitui todas as imagens. |
DELETE | /v1/moodboards/:id | Nenhum | Retorna { success: true }. As imagens vinculadas não são alteradas. |
- As imagens de um painel de inspiração são links, nunca cópias. Cada
urlé um endereçohttpouhttpsque não élocalhostnem uma rede privada, com até 2.048 caracteres. Uma legenda tem até 200 caracteres. Uma imagem que você exclui, ou que a retenção de mídia do seu plano remove, também some do painel de inspiração. nextCursoré um token opaco. Envie-o de volta comocursorpara a próxima página. Ele énullna última página.- Eles são só seus. A paleta ou o painel de inspiração de outra pessoa responde
404, como um que não existe. - Escopos: um token de app OAuth precisa de
assets:readpara as leituras e deassets:writepara as gravações. As gravações são limitadas a 30 por minuto. - As mesmas rotas estão no SDK (
client.palettes,client.moodboards), na CLI (nodaro palettes,nodaro moodboards) e nas ferramentas MCPlist_palettes,save_palette,list_moodboardsesave_moodboard. Ogenerate_imagedo MCP aceitapalette_idemoodboard_id. Não há exclusão pelo MCP.
O que uma execução recebe
- Uma paleta adiciona
color palette: <name> <hex>, …à linha de filme da seção[style], onde o visual de cor integrado entraria. Cada cor recebe o nome comum mais próximo, porque um modelo segue uma cor nomeada com mais fidelidade, e o código hexadecimal exato. A observação da paleta não é adicionada ao prompt. - Um painel de inspiração adiciona a descrição dele, em uma linha, onde o estilo integrado entraria. Sem descrição, só as imagens dele são enviadas.
- Como toda cláusula de direção, elas são as primeiras removidas quando o prompt passa do limite do modelo.
- As imagens do painel de inspiração vão ao modelo como imagens de referência, cada uma com uma linha curta. A linha diz ao modelo para tirar dela as cores, a luz, a textura e o clima, não o assunto nem a composição. Uma legenda é adicionada quando a imagem tem uma.
- As suas próprias referências vêm primeiro. As imagens que você mesmo envia mantêm as posições e a numeração delas. As imagens do painel de inspiração ocupam só as posições de referência que sobram depois delas.
- Nunca mais do que o modelo aceita. As imagens que não cabem não são enviadas, na ordem do painel de inspiração, e a resposta traz um aviso
moodboard_images_not_sent. Um modelo que não aceita imagens de referência não recebe nenhuma delas, e a descrição continua sendo enviada. - Preço. As imagens contam como referências, então uma execução tem o preço de qualquer execução com essa quantidade de referências. O preço verificado antes da execução e o preço reservado contam as mesmas imagens: as que são de fato enviadas.
aspectRatio: "auto"mantém o formato da primeira imagem que uma execução envia. Quando você não envia nenhuma imagem sua, essa é a primeira imagem do painel de inspiração.- A tarefa guarda os IDs, não cópias. Executá-la de novo usa a paleta ou o painel de inspiração como estiver nesse momento.
Erros e limites
| Status | Código | Quando |
|---|---|---|
400 | validation_error | palette: ou moodboard: sem um uuid depois, uma paleta em uma chave diferente de colorLook, um painel de inspiração em uma chave diferente de style, um deles combinado com outro valor na mesma chave, ou uma requisição que também envia presetId. field indica a chave. |
404 | direction_not_found | A paleta ou o painel de inspiração não é seu, ou não existe mais. field é direction.colorLook ou direction.style. |
As duas respostas vêm antes de qualquer criação ou cobrança. Paletas e painéis de inspiração só funcionam em generate-image: POST /v1/generate-video e POST /v1/text-to-video respondem 400 validation_error a um deles. Em um workflow salvo, um nó Gerar imagem cuja direction indica um deles é resolvido a cada execução do workflow.
Descrever o assunto por ID
subject é a mesma ideia para quem está na tomada: a pessoa, como ela está produzida e os objetos de cena no quadro. POST /v1/generate-image, POST /v1/generate-video, POST /v1/text-to-video, POST /v1/generate-character e POST /v1/generate-creature aceitam o campo:
{
"prompt": "on the seawall at dusk",
"provider": "nano-banana-pro",
"subject": {
"type": "woman",
"age": "age-30s",
"ethnicity": "east-asian",
"hairBase": "base-short-straight",
"makeup": "makeup-smoky",
"outerwear": "outerwear-trench",
"heldProp": "smartphone"
}
}- As chaves são os campos dos seletores Pessoa e Figurino e beleza, como
type,age,ethnicity,faceShape,hairColor,skinTone,makeup,outfit,outerwearefootwear. Há também três chaves de objetos:heldProp(Objeto na mão),material(Material) eanimal(Animal).GET /v1/picker-catalogs/persone/stylinglistam todos os campos e IDs. subjectedirectionnunca se sobrepõem. As chaves de um e de outro são separadas, então uma escolha nunca adiciona duas cláusulas.posepertence adirection.customAgeé o único número. Envie"age": "age-custom"com"customAge": 34para uma idade exata em anos. O valor é arredondado e mantido entre 0 e 120.- As listas têm limites por chave.
jewelry,wardrobeStateedistinctiveFeatureaceitam 3 IDs.ethnicity,regionalAesthetic,hairColor,eyeColor,lipState,eyeState,skinTexture,hairState,heldPropematerialaceitam 2. Todas as outras chaves, inclusiveanimal, aceitam 1. Os IDs excedentes são descartados. - Limites que resultam em recusa: mais de 8 entradas em uma chave, um ID com mais de 100 caracteres, mais de 128 chaves ou uma chave com mais de 64 caracteres retornam
400 validation_error. - Chaves desconhecidas são removidas, e IDs desconhecidos são ignorados.
input_data.subject, na tarefa, registra exatamente os IDs que foram usados. - As cláusulas de assunto fazem parte do seu texto, antes das cláusulas de direção e nunca na seção
[style]. Pessoa vira uma cláusula, Figurino e beleza vira outra, e escolhas sobrepostas são escritas uma vez só. Na rota de imagem, cada escolha adiciona a cláusula completa; as rotas de vídeo adicionam o termo curto, porque o quadro inicial já mostra quem é o assunto. - Em
POST /v1/generate-characterePOST /v1/generate-creature,subjectdescreve quem o retrato mostra. A redação vem logo depois deseedPromptoudescriptione das escolhas de pessoa e de figurino da própria linha, e uma escolha que os dois trazem com a mesma redação é escrita uma vez só. Essas duas rotas usam a redação de imagem fixa e nunca encurtam as cláusulas. Veja Personagens.
Sessões de geração
Uma ferramenta de criação feita sobre a API, como um criador de imagens, vídeos ou músicas, pode guardar o trabalho em sessões dentro dos seus projetos: um projeto contém sessões, e cada sessão contém itens. As mesmas sessões aparecem em todos os dispositivos, e o seu app não guarda nada por conta própria.
# 1. Open a session, optionally inside one of your projects.
SESSION=$(curl -s -X POST "https://app.nodaro.ai/v1/sessions" \
-H "Authorization: Bearer $NODARO_API_KEY" -H "Content-Type: application/json" \
-d '{"projectId": "<project-id>", "tool": "create-image", "title": "Beach"}' | jq -r .data.id)
# 2. Generate inside it: send sessionId beside the usual settings.
curl -s -X POST "https://app.nodaro.ai/v1/generate-image" \
-H "Authorization: Bearer $NODARO_API_KEY" -H "Content-Type: application/json" \
-d "{\"prompt\": \"a red car\", \"sessionId\": \"$SESSION\", \"origin\": \"create-image\"}"
# 3. Read the session's feed, newest first.
curl -s "https://app.nodaro.ai/v1/sessions/$SESSION/items" -H "Authorization: Bearer $NODARO_API_KEY"| Método | Caminho | O que faz |
|---|---|---|
POST | /v1/sessions | Cria uma sessão. Corpo: tool (obrigatório: letras minúsculas, dígitos e hifens, até 40 caracteres), projectId (opcional, um dos seus projetos) e title (opcional, até 200 caracteres). |
GET | /v1/sessions | As suas sessões, da mais nova para a mais antiga. Parâmetros: projectId (none para as sessões sem projeto), tool, includeArchived=true, limit (de 1 a 100, padrão 50) e cursor. Cada sessão traz itemCount (os itens ativos dela), removedCount (os itens dela na Lixeira), coverJobId e até quatro previewUrls: primeiro a imagem da capa, quando há uma definida, depois as imagens dos itens concluídos mais recentes dela. |
GET | /v1/sessions/:id | Uma sessão. |
PATCH | /v1/sessions/:id | Altera title (null significa sem título), archived e coverJobId: um dos itens da sessão, para abrir as prévias dela (404 quando não é um item desta sessão), ou null para voltar ao automático. O projeto de uma sessão é definido quando ela é criada. |
DELETE | /v1/sessions/:id | Exclui a sessão e os vínculos dela. As tarefas dela são mantidas e continuam em todas as outras sessões que as contêm. |
GET | /v1/sessions/:id/items | O feed: todos os itens ativos, criados na sessão ou importados, do mais novo para o mais antigo. Com removed=true, traz em vez disso os itens removidos dela, que são a parte dela na Lixeira, da remoção mais recente para a mais antiga. Cada item tem jobId, addedAt, removedAt (null quando ativo), imported, importedFrom { sessionId, title } e job no formato que GET /v1/jobs/:id retorna. Um item cuja tarefa você excluiu não está em nenhuma das duas listas. Pagine com limit e cursor. |
POST | /v1/sessions/:id/items | Importa { "jobIds": [...] }, de 1 a 100 tarefas, como vínculos, nunca cópias. Quando algum ID não é de uma das suas tarefas, ou foi excluído, nada é importado (404). Um item removido da sessão volta para onde estava. Responde { imported, requested }. |
DELETE | /v1/sessions/:id/items/:jobId | Remove um item desta sessão. Ele vai para a Lixeira e fica lá até você restaurá-lo ou excluí-lo permanentemente. Nada é limpo automaticamente. Só o vínculo se move: a tarefa, e todas as outras sessões que a contêm, ficam. ?forever=true exclui permanentemente um item que já foi removido, e a tarefa continua existindo. Em um item ativo, a resposta é 409 not_in_trash. |
POST | /v1/sessions/:id/items/:jobId/restore | Traz de volta um item removido, para onde ele estava. |
POST | /v1/sessions/:id/items/move | Move { "jobIds": [...], "fromSessionId": "…" }, de 1 a 100 itens, para esta sessão em uma só transação. Esta sessão recebe os itens, e a sessão de origem os mantém como itens removidos, então você desfaz a movimentação pela Lixeira da origem. Quando algum ID não é um item ativo de fromSessionId, nada é movido (404). Responde { moved }. |
- Toda rota que cria uma tarefa aceita
sessionId, comogenerate-image,generate-video,text-to-video,text-to-speechegenerate-music. Ela precisa ser uma das suas sessões, do mesmo lado da divisão de espaço de trabalho que a requisição. Caso contrário, a requisição responde404, e nada é criado nem cobrado. As execuções de um workflow nunca são arquivadas em uma sessão. - O
session_idda tarefa é definido uma vez, quando a tarefa é criada. Ele aparece emGET /v1/jobs/:ide emGET /v1/jobs. - Toda rota que cria uma tarefa também aceita
origin, o slug do seu app. A tarefa o guarda eminput_data.origin, eGET /v1/jobs?origin=filtra por ele. Um valor que não é um slug responde400 validation_error, e nada é criado nem cobrado. - Para mover trabalho para outro projeto, mova os itens para uma sessão desse projeto com
POST /v1/sessions/:id/items/move. O projeto de uma sessão é fixo, então é assim que um item muda de projeto. Para manter um item nos dois projetos, importe-o em vez de movê-lo. - Onde uma tarefa está agora.
GET /v1/jobsaceitaprojectId=<id>, as tarefas que uma sessão desse projeto contém agora, eprojectId=none, as tarefas que uma sessão sem projeto contém. Ele também aceitainSession=false, as tarefas que nenhuma sessão contém agora (Geral), einSession=true. Cada tarefa aparece uma só vez, não importa quantas sessões a contenham.withSessions=trueacrescentasessions: [{ id, title, projectId }]a cada tarefa, para uma visão de "tudo neste projeto".projectIdnão pode ser combinado cominSession=false(400). Esses filtros se combinam comtype,statuse os outros filtros. - A Lixeira. Os itens removidos e as tarefas excluídas vão para a Lixeira. Veja A Lixeira.
- Escopos: com um token de app OAuth, ler sessões exige
jobs:read. Criar, editar, importar e remover exigemassets:write, assim como enviarsessionIdcom uma geração. Um token de API pessoal limitado a alguns workflows não alcança essas rotas.
Cotações de execução
POST /v1/quote retorna o que a execução de um nó vai reservar, antes de você iniciá-la. Envie o tipo do nó e exatamente o corpo que você enviaria para a rota de execução dele. O servidor calcula o preço com o próprio código da rota de execução: a mesma validação do corpo, a mesma medição dos clipes de referência, o mesmo ID de crédito e a mesma conta. Por isso, a cotação é o que a execução reserva. Nada é iniciado e nada é cobrado.
- Onde: só no Nodaro Cloud. A rota exige autenticação e aceita 30 requisições por minuto.
- Quais tipos:
text-to-video,generate-video,video-to-video,video-upscale,edit-image(todos os modelos de edição),ai-avatar,cinematic-avatar,switchxesplit-into-layers. A finalização em 1080p de um rascunho do Seedance 2.5 novideo-upscaletem o preço calculado a partir do rascunho e dos clipes com que ele foi feito. Qualquer outro tipo é um400 quote_unsupportedque os lista. - Avatares e SwitchX: o
ai-avatartem o preço calculado pela faixa de duração do áudio que ele mede, como a execução o mede, ou pela duração estimada do roteiro no modo de texto. Um áudio que ele não consegue ler é o próprio400da execução. Ocinematic-avatartem o preço calculado pela resolução e pela duração exatas, e a Duração automática pelo teto de 15 segundos. Oswitchxtem o preço calculado pela faixa de blocos de quadros do clipe, medidos como a execução os mede, e pela faixa de 240 quadros quando os quadros não podem ser lidos. - Edições do Seedance: uma edição do Seedance no
video-to-videotem o preço calculado com todos os clipes enviados a ela,videoUrlereferenceVideoUrls. Veja Vídeo para vídeo para as listas de referências. - SDK:
client.nodes.quote(type, params).
{
"type": "text-to-video",
"params": {
"prompt": "edit {video:1} as follows: make it black and white",
"provider": "seedance-2-5",
"duration": -1,
"aspectRatio": "adaptive",
"referenceVideoUrls": ["https://…/clip.mp4"]
}
}A resposta é { "data": { identifier, reserve, expected?, adjustments, warnings } }:
| Campo | Significado |
|---|---|
identifier | O ID de crédito em que a execução é cobrada. |
reserve | Os créditos que a execução retém quando começa. |
expected | Os créditos que a execução deve custar de fato, quando as entradas medidas permitem calcular. Uma execução do Seedance com vídeo de referência é reservada no pior caso: os segundos de entrada mais o maior valor entre a duração pedida e o clipe mais longo. Com duração automática e todos os clipes medidos, são os segundos de entrada mais a duração do clipe mais longo, arredondada para cima até o segundo inteiro, mais um segundo. Uma execução que declara referenceTaskType: "reference" é reservada na saída mais longa do modelo. expected é a entrada mais a duração que ela provavelmente vai renderizar. Isso é a duração do clipe de origem em uma edição com duração automática, e os segundos pedidos nos outros casos. Ele nunca fica acima de reserve. |
adjustments | Uma lista de { code, message, credits? }, que explica por que o preço é esse: ref_video_length (preço pela duração dos clipes), extra_reference_images (imagens do MiniMax H3 além das 5 primeiras), auto_duration, loop_trim_addon e voiced_audio_addon (com os créditos deles), params_adjusted (uma resolução ou proporção ajustada para uma que o modelo oferece), output_size (um upscale de imagem com preço pelo tamanho da imagem que ele gera) e max_images (Dividir em camadas, com preço pelo máximo de imagens que a execução pode retornar). |
warnings | Uma lista de { code, message }: settles_to_actual (reserve é o máximo que a execução pode custar: ela é cobrada pelo que entregar, e o resto é reembolsado), ref_video_unmeasured (um clipe não pôde ser medido, então o preço é o do clipe mais longo que o modelo aceita) e image_size_unmeasured (o tamanho de uma imagem não pôde ser lido antes da execução). |
Sem um aviso settles_to_actual, reserve é o que a execução é cobrada quando termina.
- Um corpo inválido recebe o próprio
400da rota de execução. Um clipe que a execução recusaria recebe o400 video_too_longdela. Um modelo que esta implantação não oferece recebe o403 model_not_availableda execução, e um nó que ela não oferece a você recebe o403 node_not_availableda execução. - Um clipe guardado no Nodaro, como um upload ou um resultado gerado, fica na memória por 15 minutos depois de medido. Cotar e depois executar o mesmo corpo mede o clipe uma vez só.
- Uma cotação verifica o corpo e o preço, não o seu saldo nem o seu plano. A execução ainda pode responder
402. Algumas verificações que só a execução faz ainda podem recusar um corpo cotado, por exemplo um modelo que precisa de um quadro inicial.
O Nodaro Image Upscale (edit-image com provider: "nodaro-image-upscale") tem o preço calculado pelo tamanho da imagem que gera. A cotação dele lê a imagem que você envia, verifica e mede como a execução faz, não guarda nada e responde o preço exato desse tamanho. O id de crédito indica a faixa da saída, por exemplo nodaro-image-upscale:2K para uma imagem de 1024 × 1024 com upscaleFactor: "2". Uma imagem cujo tamanho não pode ser lido é cotada pela reserva, com os avisos image_size_unmeasured e settles_to_actual.
- Um link para outro site segue a configuração de importação de links desta implantação, e responde
403 link_imports_disabledquando ela está desligada. - Uma imagem que a execução recusaria, como uma grande demais ou ilegível, recebe o próprio
400da execução. - Uma imagem externa tem 15 segundos para chegar. Depois disso, a cotação responde
503 input_timed_out: tente de novo, ou envie a imagem por upload. - Os outros modelos de edição são cotados pelo próprio preço. O upscaler com preço pelo fator pode custar mais em uma saída muito grande, e um ajuste
output_sizeavisa isso.
Dividir em camadas é cotado pela reserva: o máximo de imagens que a execução pode retornar (maxLayers + 1, com a base) pelo preço do tamanho. A execução é cobrada só pelas imagens que retornar. Por isso a cotação traz o aviso settles_to_actual e um ajuste max_images que diz quantas imagens ela reserva.
{ "type": "split-into-layers", "params": { "imageUrl": "https://…/poster.png", "maxLayers": 5, "size": "1K" } }O identifier dessa cotação é split-into-layers:1k:6: 5 camadas e a base, pelo preço que 1K e 1.5K compartilham.
Descobrir nós
GET /v1/nodes lista todos os tipos de nó que o servidor conhece, e GET /v1/nodes/:type retorna um deles. Os dois são públicos, não precisam de token e ficam em cache por 5 minutos. Um tipo desconhecido retorna 404 not_found.
curl -s https://app.nodaro.ai/v1/nodes/generate-image | jq .dataconst { data: nodes } = await client.nodes.list()
const imageNodes = nodes.filter((n) => n.category === 'ai-image')
const { data: generateImage } = await client.nodes.get('generate-image')
console.log(generateImage.providers)nodaro nodes list --category ai-image
nodaro nodes get generate-image{
"data": {
"type": "generate-image",
"label": "Generate Image",
"category": "ai-image",
"description": "Generate an image from a text prompt using an AI provider.",
"outputType": "image",
"creditCost": "3-682",
"providers": ["nano-banana-pro", "gpt-image-2", "gpt-image-2-5-flare", "seedream-5-pro", "z-image"],
"capabilities": ["supports-reference-image", "supports-aspect-ratio"],
"inputSchema": {
"fields": [
{ "key": "prompt", "type": "text", "required": true },
{ "key": "provider", "type": "select", "options": ["nano-banana-pro", "gpt-image-2"] },
{ "key": "aspectRatio", "type": "select" },
{ "key": "promptPrefix", "type": "text" },
{ "key": "promptSuffix", "type": "text" }
]
}
}
}| Campo | Significado |
|---|---|
type | O tipo do nó. Para a maioria dos tipos de nó, ele também é a rota: POST /v1/<type>. |
label, category, description | Como o editor nomeia e agrupa o nó. |
outputType | text, image, video, audio, data ou none. |
creditCost | O custo do nó em créditos, ou a faixa de custo. É o preço cobrado por uma execução, o mesmo número do botão Executar do nó. No Cortar vídeo, no Vídeo em loop e no Combinar vídeos, ele é, em vez disso, o preço de um bloco de 5 segundos, e uma execução custa um certo número de blocos. Só no Nodaro Cloud: as edições sem créditos omitem o campo. |
estimate | true quando creditCost é uma estimativa: a chamada típica de um nó de LLM medido com o modelo padrão dele. A execução é cobrada pelo uso real, então mostre o valor como ≈N. O Escolher o melhor lista uma faixa "0-N" marcada com estimate: das estratégias gratuitas até a chamada típica do juiz de IA. Ausente para um preço fixo. Um nó de LLM medido cujo modelo padrão ainda não tem preço lista creditCost: "unpriced", e uma execução nesse modelo é recusada. Veja Erros. |
creditRate | Para um nó cobrado por unidade da própria medida, cujo creditCost é uma palavra e não um número. Hoje, esse nó é o Quadros dos falantes, com creditCost "per-1000-frames". O objeto é { identifier, unit, creditsPerUnit, minUnits, rounding, note }. creditsPerUnit é o preço exato de uma unidade, sem arredondamento. Com rounding: "ceil-run-total", uma execução de N unidades (no mínimo minUnits) é cobrada ceil(N × creditsPerUnit), arredondado para cima uma vez. Não multiplique o preço de uma unidade de /v1/credits/model-cost. |
providers | Os IDs de modelo que o nó aceita em provider. |
capabilities | Flags de recursos, como supports-reference-image. |
inputSchema.fields | As configurações do nó, com o tipo, se são obrigatórias e as opções. |
Todo nó que recebe um prompt também lista promptPrefix e promptSuffix: texto adicionado antes e depois do prompt. Veja Texto antes e depois do prompt. Nós com limites por modelo trazem campos extras:
| Campo | Significado |
|---|---|
maxDurationSec | A duração máxima que o nó aceita. |
sparseProviders | Modelos com poucas durações de segmento. Um valor entre elas é ajustado para a mais próxima. |
providerResolutions | As resoluções de cada modelo, por exemplo { "minimax-h3": ["2K", "768P"] }. |
providerResolutionWire | O valor exato a enviar para cada resolução, por exemplo 768P, e não 768p, para o nível mais barato do MiniMax H3. |
soundtrack | No Gerar vídeo Pro: o servidor aceita a entrada soundtrack de áudio original. |
O descritor cresce com o tempo, então ignore os campos que você não conhece. Os mesmos dados alimentam a referência de nós.
Descobrir modelos
GET /v1/models retorna o catálogo de modelos, agrupado por tipo e por fabricante. Ele é público, fica em cache por 5 minutos e traz os mesmos dados que a ferramenta list_models do MCP retorna.
Um modelo que esta implantação não oferece não aparece na lista. Isso inclui um modelo que um administrador desativou. A mesma desativação recusa uma execução desse modelo com 403 model_not_available. Um cliente que guarda a lista pelos 5 minutos ainda pode indicar um modelo assim.
curl -s "https://app.nodaro.ai/v1/models?kind=video&mode=i2v" | jq '.totalModels'const catalog = await client.models.list({ kind: 'video', mode: 'i2v' })
for (const section of catalog.sections)
for (const family of section.families)
for (const m of family.models) console.log(m.id)nodaro models list --kind video --mode i2vA resposta é { sections, recommendations, totalModels }. Todo modelo indica o fabricante e traz a marca dele, exceto um modelo que a instância oferece com a própria marca. Esse modelo não indica fabricante: maker fica ausente e logoUrl é null.
| Campo | Tipo | Significado |
|---|---|---|
maker | { id, name }, ausente em um modelo oferecido com a própria marca da instância | A empresa que criou o modelo. id é estável, um por empresa, escrito em minúsculas com hifens, como google, black-forest-labs ou bytedance. Associe os seus próprios arquivos a ele e trate um ID que você não conhece, porque um servidor mais novo pode adicionar fabricantes. Nem sempre é a family em que o modelo é agrupado. |
logoUrl | string ou null | A marca oficial do fabricante como SVG na CDN de mídia deste servidor, ou null quando o servidor não publica uma. Nesse caso, desenhe uma alternativa, como o nome ou a inicial do fabricante. Use o endereço como foi informado: ele traz a versão do arquivo, então uma marca substituída chega em um novo endereço. |
GET /v1/model-makers retorna só os fabricantes, para um app que desenha marcas e não precisa do catálogo. A resposta é { makers: [{ id, name, logoUrl }] }, com todos os fabricantes que a plataforma conhece. Os campos são os mesmos de cima, então as duas rotas nunca divergem. A rota é pública e fica em cache por 5 minutos, como GET /v1/models. Ela lista um fabricante mesmo quando nenhum dos modelos dele é oferecido.
A ferramenta MCP list_models traz maker, mas não logoUrl.
Cada modelo também traz os próprios recursos (modes, features, aspectRatios, resolutions, qualities, backgrounds, durations, e as regras de tamanho e os formatos de saída abaixo), o pricing em créditos por variante no Nodaro Cloud e promptTips curtas. Ele também traz doctrineCovered, que só é true quando existe um guia de prompts com fontes para a família do modelo. Os créditos de pricing são o preço cobrado por uma execução, o mesmo número do botão Executar no editor. Um modelo de vídeo que aceita um tipo de tarefa de referência lista os valores em referenceTaskTypes: ["reference", "edit", "extend"] no seedance-2-5, e ausente em todos os outros modelos.
Um modelo de fala, como um modelo de texto para fala ou de diálogo, lista uma segunda linha de pricing, <model>:per-100-chars, onde a fala é cobrada pelo tamanho. Essa linha é o preço de cada 100 caracteres iniciados do texto enviado, com um mínimo de 8 unidades por execução. Uma requisição é precificada como um todo e arredondada uma única vez, então N × os créditos da linha, com N = max(8, ceil(characters / 100)), é só um limite superior. O preço exato é o identificador <model>:per-100-chars:<N>u, que POST /v1/credits/model-costs e GET /v1/credits/model-cost respondem. Cote por esse valor, não por um produto. Onde a linha não existe, todo identificador :<N>u também não existe: cote pela linha fixa do modelo. Veja Preços exatos de execuções cobradas por unidade.
Alguns modelos de imagem renderizam menos tamanhos em certas proporções, ou um fundo transparente em um tamanho só, e alguns modelos declaram o tamanho em que cai uma requisição que não indica nenhum. As entradas deles dizem isso com estes campos, que não existem nos outros modelos nem em um servidor mais antigo:
| Campo | Tipo | Significado |
|---|---|---|
defaultResolution | string | O tamanho em que cai uma requisição que não indica resolution, escrito como em resolutions, quando o modelo declara um: 1K no FLUX 3 Klein (flux-3-klein, flux-3-klein-i2i), 2K no Seedream 5.5 e no MiniMax H3 Image e nos modelos de edição -i2i deles, 720p no PixVerse V6 Max. Leia este campo em vez de supor que a primeira entrada de resolutions é o padrão. |
resolutionsByAspectRatio | { [ratio]: string[] } | As proporções em que o modelo renderiza menos tamanhos que resolutions, cada uma com os tamanhos que renderiza nela. Uma proporção que não está listada renderiza todos os tamanhos de resolutions. Um tamanho maior é executado, e cobrado, no maior tamanho que a proporção renderiza até ele, e adjustments informa isso. |
transparentResolution | string | O único tamanho em que um fundo transparente é renderizado. Uma requisição transparente em outro tamanho é executada, e cobrada, neste tamanho. |
backgroundOnlyAtTransparentResolution | true | O modelo só aceita uma configuração de fundo em transparentResolution. Em qualquer outro tamanho, opaque é renderizado como auto, informado em adjustments. |
O GPT Image 2.5 (gpt-image-2-5-flare, gpt-image-2-5-sunburst e os modelos de edição -i2i deles) renderiza 27:16, 16:27, 9:8 e 8:9 só em 1K, e um fundo transparente em 1K:
{
"id": "gpt-image-2-5-flare",
"aspectRatios": ["auto", "1:1", "16:9", "9:16", "27:16", "16:27", "9:8", "8:9"],
"resolutions": ["1K", "2K", "4K"],
"resolutionsByAspectRatio": { "27:16": ["1K"], "16:27": ["1K"], "9:8": ["1K"], "8:9": ["1K"] },
"backgrounds": ["auto", "opaque", "transparent"],
"transparentResolution": "1K",
"backgroundOnlyAtTransparentResolution": true
}O exemplo mostra só esses campos, e não todas as proporções. Um menu de tamanhos oferece resolutionsByAspectRatio[ratio] quando a proporção escolhida está listada ali, e resolutions caso contrário. O GPT Image 2 (gpt-image-2 e gpt-image-2-i2i) não lista resolutionsByAspectRatio: ele renderiza todas as proporções que oferece, incluindo auto e 1:1, em 1K, 2K e 4K. O GPT Image 2.6 Flare e o Sunburst listam transparentResolution: "1K" e nenhum resolutionsByAspectRatio.
Um modelo que grava mais de um tipo de arquivo lista os formatos dele. Estes campos não existem nos outros modelos nem em um servidor mais antigo:
| Campo | Tipo | Significado |
|---|---|---|
outputFormats | string[] | Os arquivos que o modelo grava (png, jpeg, webp, gif, svg), o padrão primeiro. São os valores que outputFormat aceita. |
gifFrameSize | number | Com gif: o tamanho em pixels de cada quadro quadrado. Um GIF ignora aspectRatio e resolution. |
gifFrames | { min, max, default, values? } | Com gif: os quadros que gifFrames aceita, um número inteiro de min a max, ou um dos values quando o modelo aceita só alguns. |
gifFrameDurationMs | { min, max, step, default } | Com gif: quanto tempo cada quadro aparece, em milissegundos. |
svgLevels | string[] | Com svg: os níveis de detalhe que svgLevel aceita, o padrão primeiro. |
{
"id": "gpt-image-2-6-flare",
"outputFormats": ["png", "jpeg", "webp", "gif", "svg"],
"gifFrameSize": 512,
"gifFrames": { "min": 2, "max": 16, "default": 9 },
"gifFrameDurationMs": { "min": 20, "max": 2000, "step": 10, "default": 200 },
"svgLevels": ["standard", "detailed", "max"]
}| Parâmetro | Valores | Filtra por |
|---|---|---|
kind | image, video ou audio | Um tipo de mídia |
mode | Por exemplo, t2i, i2v, t2v, tts, video-analysis | Uma operação |
family | Um fabricante, por exemplo Google ou Bytedance | Um fabricante |
featuredOnly | true | Modelos em destaque |
As páginas de modelos mostram o mesmo catálogo.
O que esta implantação oferece a você
GET /v1/surface/availability diz o que um app deve mostrar à pessoa com login: os tipos de nó, os modelos, as fontes do Web Scrape e os mundos que esta implantação oferece a ela. Ao contrário de GET /v1/nodes e GET /v1/models, a resposta depende de quem pergunta, então ela vem com Cache-Control: private, no-store. O token é opcional, e sem login a resposta é a de um usuário. Nenhum escopo é necessário.
{
"nodes": { "denied": ["social-publish"], "hiddenFromUsers": [] },
"models": { "denied": ["flux-flex"], "restricted": true },
"webScrapeSources": { "denied": [], "hiddenFromUsers": [] },
"worlds": [
{ "id": "image", "enabled": true },
{ "id": "video", "enabled": false }
]
}| Campo | Significado |
|---|---|
nodes.denied | Os tipos de nó que não são oferecidos a você. Salvar ou executar um deles é recusado com 403 node_not_available. |
nodes.hiddenFromUsers | Vazio para quem não é administrador: os tipos de nó que um administrador pode usar e os usuários da implantação não podem. |
models.denied | Os ids de modelo que ninguém nesta implantação recebe. Uma execução de um deles responde 403 model_not_available. |
models.restricted | true quando a implantação restringe os modelos que oferece. Um modelo que um administrador só desligou aparece em models.denied sem deixar este campo true. Onde ele é true, o editor de workflows começa um nó novo em um modelo que o menu dele oferece. Um servidor anterior ao campo o omite: leia isso como false. |
webScrapeSources.denied, webScrapeSources.hiddenFromUsers | As fontes do Web Scrape retiradas junto com o nó que as governa, nas mesmas duas visões. A fonte do Instagram segue o nó do Instagram. |
worlds | Todos os mundos do cabeçalho compartilhado do site, na ordem de exibição da implantação: explore, image, video, music, trends, motion, voice, app (o editor de workflows) e studio. Um servidor mais novo pode acrescentar um mundo, então trate um id que você não conhece. |
worlds[].enabled | true quando a implantação deixa o mundo passar e todos os tipos de nó que o mundo executa estão disponíveis para você. image executa generate-image, video executa generate-video e text-to-video, music executa suno-generate, trends e motion executam cast-swap, e voice executa voice-changer-pro. explore, app e studio não executam nenhum nó próprio. |
worlds informa apenas as configurações de disponibilidade da implantação. Se a edição oferece um nó, isso é decidido pelo servidor. A tabela de qual mundo executa qual nó é publicada como WORLD_REQUIRED_NODE_TYPES, em @nodaro/shared/runtime-config. No SDK, é client.surface.availability().
Antes de essa resposta chegar, ou quando ela não pode ser lida, um app pode avaliar a implantação pelas listas da configuração de ambiente de execução dela: surface.nodes, surface.models e surface.worlds. nodeListsWithhold, listsWithhold e worldOffered, em @nodaro/shared/runtime-config, aplicam a essas listas a mesma regra que o servidor aplica. O editor de workflows funciona assim.
Modelos com um filtro de conteúdo forçado
GET /v1/provider-safety/locks responde { "forcedOn": ["seedance-2"] }: os modelos em que esta implantação força o filtro de conteúdo ligado. Um cliente que oferece uma escolha de filtro para um desses modelos deve mostrá-la ligada e travada. A lista fica vazia quando nenhum filtro é forçado.
Descobrir valores de seletores
Os seletores de Controles criativos têm catálogos públicos de IDs válidos, os valores que direction e subject aceitam:
| Método | Caminho | O que retorna |
|---|---|---|
GET | /v1/picker-catalogs | Todos os seletores: nodeType, label, kind, o campo ou os campos, optionCount e imageCount. imageCount é 0 para todos os seletores em uma implantação que desativou as imagens. |
GET | /v1/picker-catalogs/:nodeType | As opções de um seletor. ?detail=full adiciona a description e o promptHint de cada opção (para uma opção de style, o texto de imagem dela), ?category= filtra um seletor de campo único, e ?field= retorna um campo de um seletor de vários campos. |
GET | /v1/catalogs | Todos os catálogos em uma chamada, como a implantação os organizou. data aparece quando a implantação registrou pacotes de catálogo ou mostra imagens próprias nos seletores. |
POST | /v1/text-to-picker | “AI Fill”: escolhe IDs para vários seletores a partir de uma descrição de cena em texto livre. Sem llmModel, ele roda o Gemini 3.8 Flash. Ele é cobrado pelos tokens que as chamadas dele usam, pela tarifa do modelo. Veja Catálogos de seletores. |
Toda opção traz id, label e term (a frase curta para usar em um prompt), além de imageUrl quando a opção tem imagem. Uma implantação pode desativar as imagens com catalogs.images no perfil de superfície. As respostas dela então não trazem imageUrl nem imageSrcSet em nenhuma opção. Uma implantação que mostra imagens próprias pode acrescentar imageLargeUrl, uma imagem ampliada para onde um seletor mostra a opção grande. A imagem própria pode ser um caminho no site dela, como /brand/style/noir.webp: resolva o caminho a partir do endereço em que você chamou a API. Veja Imagens. Os catálogos também vêm como dados no pacote npm @nodaro/prompts. Leia Catálogos de seletores para ver os formatos completos. No terminal: nodaro pickers list, nodaro pickers get mood --full e nodaro pickers analyze "<text>".
Saída estruturada de LLM
POST /v1/llm/structured faz uma chamada a um modelo de linguagem cuja resposta é forçada a seguir um JSON Schema que você fornece, validada e retornada como objeto. A chamada é cobrada pelos tokens que realmente usou, pela tarifa do modelo na via que a atendeu. Os tokens incluem o seu prompt de sistema, a entrada e o schema, cada nova pergunta de validação e cada troca de via, e a resposta. Veja Como as chamadas de LLM são cobradas.
- Antes da chamada, uma reserva é feita: a primeira tentativa no limite de saída do modelo. Um saldo abaixo da reserva é recusado com
402(“São necessários até N créditos”). - Depois da chamada, a chamada é cobrada pelo que usou. Em geral, isso é menos que a reserva.
- A cotação de uma chamada típica vem de
POST /v1/credits/model-costscom a chavellm-structured:<model>. É uma estimativa, então mostre-a como≈N. Veja Créditos. - Falhas: uma falha que o provedor cobrou é cobrada por esse uso, e o erro diz quanto. Exemplos são uma resposta que nunca passou na validação depois das novas tentativas, uma recusa ou uma resposta cortada no limite. Uma falha que o provedor não cobrou é reembolsada.
O Claude Fable 5 é oferecido nesta rota.
{
"system": "You write production plans.",
"input": "A rainy chase through Rome.",
"jsonSchema": {
"type": "object",
"properties": { "title": { "type": "string" } },
"required": ["title"]
}
}A resposta é { jobId, output, usage: { inputTokens, outputTokens } }, em que output tem o formato do seu schema.
- Campos:
system,input,jsonSchemae, opcionalmente,schemaName(até 64 caracteres),llmModel,reasoningEffort,maxRetries,origin,advancedMode,temperatureemaxTokens.systemaceita até 200.000 caracteres, para caber um vocabulário em que o seu schema escreve.inputaceita de 1 a 100.000 caracteres. - Modelo: sem
llmModel, a chamada roda no Gemini 3.6 Flash. - Schema: a raiz precisa ser um schema de objeto simples, com até 64 KB e 20 níveis de profundidade. Ele pode usar
properties,required,additionalProperties,items, os tipos básicos,enum,const, os limites numéricos e de comprimento,multipleOf,exclusiveMinimumedescription.anyOfeoneOfsó são aceitos abaixo da raiz.not,if,then,else, as palavras-chavedependent,$refexterno e combinadores na raiz retornam400. UmanyOfde ramosrequiredabaixo da raiz é aceito, mas não é aplicado, então verifique você mesmo as regras que envolvem vários campos. - Novas tentativas:
maxRetries, de 0 a 3, com padrão 2, é quantas vezes uma resposta inválida volta ao modelo com o erro de validação. - Amostragem:
maxTokensvale em toda chamada e não pode passar do limite do próprio modelo.temperatureé ignorado, a menos que você também envieadvancedMode: true, que executa a chamada na API do próprio fabricante do modelo, pela tarifa dessa via. - Duração: a chamada é síncrona e pode levar vários minutos. Cada tentativa pode levar até 240 segundos em cada uma das duas vias, então o pior caso é de 24 minutos com o
maxRetriespadrão e de 32 minutos com o máximo. Aumente o timeout do seu cliente HTTP ou use a forma de tarefa abaixo. OtimeoutMspadrão do SDK, de 60 segundos, é curto demais. - Erros:
400 validation_error,400 advanced_mode_unavailable,401,402,500 internal_error,502 llm_errordepois que as novas tentativas se esgotam,502 advanced_mode_unavailablee503 provider_unavailable. VejaadvancedModeacima para a recusaadvanced_mode_unavailable. Mais dois códigos dizem respeito à reserva:409 job_cancellede503 job_start_failed. Veja Erros.
No SDK, chame client.llm.structured(body).
Como tarefa
POST /v1/llm/structured/jobs recebe o mesmo corpo e responde { jobId } na hora. Consulte periodicamente GET /v1/jobs/:id/status: em completed, output_data é { output, inputTokens, outputTokens }, e em failed, error_message diz o motivo. Encontre os seus rascunhos de novo com GET /v1/jobs?type=llm-structured&origin=<your app>. Três campos extras são aceitos:
label: um nome de exibição para a tarefa, com até 120 caracteres.videoUrl: gera o rascunho a partir de um vídeo. Primeiro o vídeo é analisado, em uma tarefa separada que também é sua, pelo preço da análise de vídeo, e a análise é adicionada ao seuinput. Durante a execução,output_data.stageéanalyzinge depoisdrafting.videoAnalysis:{ llmModel?, selectionMode? }para essa análise.
A reserva do rascunho é feita quando a tarefa é criada, com llm-structured:<model> (com :direct na própria API do provedor). A tarefa é então cobrada pelo que o rascunho usou. Cancelar o rascunho com POST /v1/jobs/:id/cancel também cancela uma análise em andamento. Uma análise recusada libera todos os créditos reservados para o rascunho. Em uma instalação que envia as chamadas de modelo de linguagem para o nodaro.ai, a forma de tarefa retorna 503 provider_unavailable: nesse caso, use a chamada síncrona. No SDK, chame client.llm.structuredJob(body).
Perguntas frequentes
Como gerar uma imagem com a API do Nodaro?
Envie POST /v1/generate-image com os campos prompt e provider. A resposta traz um jobId. Consulte periodicamente GET /v1/jobs/:id/status até o status ser completed e leia output_data.imageUrl. No SDK, client.nodes.runAndWait faz as duas etapas.
Quais nós posso executar pela API?
Todos os tipos de nó que GET /v1/nodes lista. A rota é POST /v1/ seguido do tipo do nó, com as configurações do nó como corpo JSON. Alguns nós de texto usam um caminho mais longo, como /v1/llm-chat/generate.
O que é o objeto direction?
Um mapa simples de IDs de seletores, como { "shotSize": "wide-shot", "timeOfDay": "golden-hour" }, que você envia com uma geração de imagem ou de vídeo. O Nodaro escreve no prompt a própria redação testada para cada ID. Os IDs válidos vêm de GET /v1/picker-catalogs.
Como manter um personagem consistente pela API?
Envie a imagem do personagem em connectedReferences, com source wired-character e o nome do personagem em defaultName. A rota anexa a imagem e escreve as instruções de identidade no prompt, como o editor faz.
Os endpoints de descoberta precisam de token?
Não. GET /v1/nodes, GET /v1/models, GET /v1/picker-catalogs e GET /v1/catalogs são públicos e ficam em cache por 5 minutos. Eles expõem apenas dados de catálogo, nunca nada sobre a sua conta.
O que acontece quando o meu prompt com os IDs de direction fica longo demais para o modelo?
O Nodaro remove primeiro as cláusulas de direção, uma de cada vez a partir do final, até o prompt caber. As cláusulas de assunto são as últimas a sair, e o seu próprio texto e as suas referências nunca são removidos para dar lugar a elas.
Páginas relacionadas
Tarefas
Workflows
Catálogos de seletores
Gerar imagem
Modelos de IA no Nodaro
Última atualização
Workflows
Execute workflows do Nodaro pela API com novas entradas, aguarde ou consulte periodicamente o resultado; liste, crie, atualize, exporte e mova workflows.
Tarefas
Consulte status e resultados de tarefas, filtre a sua lista, avalie e favorite resultados, leia o tamanho das imagens, verifique 100 tarefas e cancele tarefas.