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

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 200 com { "jobId": "…" }. O processamento roda em um worker, e você consulta a tarefa periodicamente com GET /v1/jobs/:id/status até o status ser completed. 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-video e generate-image também podem incluir warnings. Veja Correções de parâmetros.
  • Os nós inline, como combine-text, retornam o resultado completo na hora, sem jobId.
  • Os extratores, como web-scrape, também respondem na hora. A resposta traz um jobId, 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-chatPOST /v1/llm-chat/generate
after-effectsPOST /v1/after-effects/generate
motion-graphicsPOST /v1/motion-graphics/generate
lottie-overlayPOST /v1/lottie-overlay/generate
3d-titlePOST /v1/3d-title/generate
image-to-textPOST /v1/image-to-text/describe
video-composerPOST /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, xhigh ou max, 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 que temperature, maxTokens e toda a faixa de raciocínio têm efeito. A chamada é cobrada pela tarifa por token dessa via. Um modelo sem essa via retorna 400 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_unavailable antes de qualquer cobrança, ou 502 advanced_mode_unavailable no 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=2K

Consultar 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.status

Ler 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:

ErroQuando
InsufficientCreditsError, StorageExceededError, JobBlockedErrorA execução foi recusada antes de qualquer tarefa começar.
ModelUnavailableErrorEsta implantação não oferece o modelo, ou um administrador o desativou. Escolha outro modelo.
JobFailedErrorA tarefa terminou como failed ou cancelled. O erro traz o jobId e a mensagem de erro.
JobTimeoutErrorO tempo de maxMs passou. A tarefa não é cancelada e geralmente ainda termina: busque-a depois com client.jobs.get(jobId).
JobAbortedErrorO seu signal foi disparado.
JobHeldErrorA 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 (promptPrefix e promptSuffix).
  • Os marcadores {name || default} preenchidos com os padrões deles.
  • O style dela, 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-2 e a proporção 16: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 em presetVariables. Sem ele, a rota responde 400 com code: "preset_variables_required" e tokens: ["BRAND"].
  • Um presetId desconhecido responde 404 preset_not_found.
  • A verificação de créditos calcula o preço da requisição depois de aplicar a predefinição. Nem presetId nem presetVariables ficam guardados na tarefa.
  • Uma predefinição que trabalha a partir de fotos tem minReferences acima de 0. Envie essa quantidade de imagens em referenceImageUrls. Veja Predefinições.
  • Uma predefinição se combina com count e models. 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 direction dela indica palette:<id> ou moodboard:<id>, enviada por você ou salva na predefinição, a rota responde 400 validation_error com field indicando 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 que provider aceita) substitui provider e 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, count vale por modelo: models: ["gpt-image-2", "flux-2-max"] com count: 2 cria 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_credits com required igual 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 chave K: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 responde 409 batch_in_progress depois de 15 segundos; tente de novo. Repetir uma chave com um corpo diferente, ou em outra rota, responde 422 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, o 500 as nomeia em error.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 recebe seed + i, então as imagens são diferentes.
  • Com uma predefinição, count cria N imagens da requisição da predefinição. Com models, 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.batchId e a posição dela em input_data.batchIndex. GET /v1/jobs?batchId=<id> lista as tarefas.
  • Recusado antes de qualquer criação com 400 validation_error: count fora de 1 a 4, menos de 2 ou mais de 4 models, um modelo repetido ou desconhecido, models junto com provider, ou mais de 8 imagens. Um modelo que a implantação não oferece responde 403 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? }:

  • prompt aceita de 1 a 500 caracteres, por exemplo "the person".
  • threshold vai 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).
  • maxLayers vai 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.
  • prompt aceita 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.
  • sessionId e origin funcionam como em toda rota que cria tarefas. Um cabeçalho Idempotency-Key opcional 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, e layers lista o arquivo de cada camada, de baixo para cima.
  • layerData traz 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.
  • width e height são os pixels do próprio arquivo da camada. Uma camada é recortada no próprio elemento, então redimensione-a para a box dela 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, resolution e aspectRatio são repassados como estão: um valor que o modelo não aceita é ignorado, nunca recusado. O Seedance 2 é o único com 4k e adaptive. 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, em 480p ou 720p (o padrão). Uma requisição em 1080p renderiza e é cobrada em 720p. Ele aceita até 10 imagens, 5 vídeos e 5 clipes de áudio de referência. Mais que isso responde 400 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 o referenceTaskType funcionam como no Seedance 2.5. Ele não tem draft, que é ignorado, e não aceita seed. Em POST /v1/video-to-video, ele é um modelo de edição ao lado do seedance-2-5.
  • O MiniMax H3 aceita resolution 2K ou 768P, escritos exatamente assim. GET /v1/nodes/:type lista o valor a enviar em providerResolutionWire.
  • 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.
  • characterReferences manté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 responde 400 character_references_unsupported. Um quadro inicial ou um quadro final na mesma requisição responde 400 character_references_with_start_frame ou 400 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 um bodyImageUrl. Uma requisição acima do orçamento responde 400 character_references_quota. No Gemini Omni Flash 1.2, os personagens não contam em nenhum orçamento, e um voice responde 400 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 aceita referenceImageUrls (até 10), referenceVideoUrls (até 5, cada um de 2 a 30 segundos; um 6º responde 400 reference_videos_over_limit), characterReferences (até 7) e referenceAudioUrls (até 3). Mais que isso responde 400 antes de qualquer reserva: character_references_quota quando a requisição traz characterReferences, e validation_error nos outros casos. Um imageUrl ou endFrameUrl conta 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, bodyImageUrl e até 3 extraImageUrls sã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 um voice responde 400 character_voice_unsupported; envie os clipes de voz como referenceAudioUrls. 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 referenceAudioUrls toca 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_2 vira @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: false manté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 inicial imageUrl, até 8 quadros intermediários como referenceImageUrls, em ordem, e um endFrameUrl. Um quadro final sozinho é permitido, e nenhum quadro é texto para vídeo. O total de quadros é limitado pela duration: 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, responde 400 validation_error antes de qualquer reserva. No prompt, os quadros são @first_frame, @keyframe_N e @last_frame, e @image_N é reescrito como @keyframe_N. aspectRatio só vale sem nenhum quadro. Ele não aceita vídeos de referência, áudio nem personagens.
  • Os dois modelos Kling 4.0 aceitam uma duration de 3 a 30 segundos inteiros (padrão 5) e uma resolution de 720p (padrão) ou 1080p; 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:1 ou 21: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. Um imageUrl sem referenceImageUrls, referenceVideoUrls nem characterReferences é o quadro de abertura exato. Nesse caso, aspectRatio nã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, um imageUrl entra nas imagens de referência depois das suas, como no kling-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) e characterReferences (até 7 sujeitos nomeados, como no kling-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, responde 400 antes de qualquer reserva. Não há vozes separadas: o clipe N de referenceAudioUrls (até 7) vira a voz da entrada N de characterReferences, em ordem. Um personagem precisa de 2 a 4 imagens, ou de um videoUrl, 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_N perde o @. keepOriginalSound funciona como no kling-4. Não há audioSoundtrack.
  • Configurações do Kling 4.0 Flash. duration vai de 3 a 20 segundos (padrão 5). O modelo renderiza só em 720p: qualquer resolution renderiza e cobra 720p. aspectRatio é como no kling-4, o som está sempre ativado, não há seed, e o prompt pode ter até 8.000 caracteres. Não há quadro final: um endFrameUrl junto com um imageUrl ou com referências não é enviado ao modelo. Um endFrameUrl sozinho em POST /v1/generate-video responde 400 (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. No POST /v1/generate-video, o imageUrl é o quadro inicial exato, e o clipe assume o formato dele. No POST /v1/text-to-video, aspectRatio é 16:9 (padrão), 4:3, 1:1, 3:4, 9:16, 2:3, 3:2 ou 21:9; outra proporção vai para a mais próxima delas. duration vai de 1 a 15 segundos (padrão 5). resolution é 360p, 540p, 720p (padrão) ou 1080p, 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. Sem sound, generateAudio: false também o desliga, e sound vale 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 um imageUrl, o quadro inicial exato. Um endFrameUrl é o quadro final exato, e a mesma URL nos dois faz um loop sem emenda. Até 4 quadros intermediários vão em referenceImageUrls, 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 endFrameUrl sem imageUrl respondem 400 image_required. duration vai de 1 a 15 segundos (padrão 8). resolution é 480p (padrão), 720p ou 1080p, 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_resolution antes 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 videoUrl opcional de uma entrada de characterReferences é 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. imageUrl e description continuam 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 com referenceVideoUrls. 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 responde 400 antes de qualquer reserva: character_videos_over_limit, reference_videos_over_limit, character_video_shared, ou video_too_long para um clipe fora de 3 a 8 segundos. Um clipe ilegível responde 400 character_video_unreadable. Qualquer outro modelo responde 400 character_video_unsupported. Veja Personagens em vídeo.
  • voice fixa uma voz em uma referência de personagem entre clipes: { preset, description?, exampleLine? }, em que preset é um dos IDs de voz do Gemini. Uma requisição pode fixar até 3 vozes diferentes, ou responde 400 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.

ValorO que faz
autoO padrão, também quando o campo não vem. Nada é declarado, e o modelo decide pelo prompt.
referenceA mídia só guia um clipe novo. A solicitação mantém a proporção e a duração com que foi enviada.
editO 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.
extendO 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 em referenceTaskTypes no GET /v1/models.

  • O que ele muda é informado. Uma proporção ou duração que edit ou extend substitui volta em adjustments e, no /v1/generate-video, também em warnings. Uma proporção automática não é substituída, porque com um vídeo de referência ela já roda em adaptive.

  • 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/quote com o mesmo corpo calcula o preço do mesmo jeito. Uma execução reference com 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: true declara o tipo exatamente como a mesma solicitação sem draft, em 480p. A finalização em 1080p de um rascunho edit renderiza 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.referenceTaskType da tarefa só é preenchido quando um tipo foi declarado.

  • POST /v1/video-to-video com provider: "seedance-2-5" sempre pede edit, seja qual for o corpo. A edição é declarada quando todos os clipes, o videoUrl de origem e os referenceVideoUrls, 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. auto também é removido. Isso vale para POST /v1/workflows, PATCH /v1/workflows/:id e POST /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 entrada wired-character passa 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 pelo id que 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 simples referenceImageUrls, 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, vira defaultName; 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-image també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 referenceImageUrls simples, na ordem, então {image:1} é a primeira URL que você enviou. Isso inclui uma requisição cujas únicas outras referências são describedReferences.
  • Com pelo menos uma entrada em connectedReferences, N conta as entradas de connectedReferences, na ordem. As referenceImageUrls simples 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 de connectedReferences.
  • Um token sem imagem na posição dele vira o rótulo dele: {image:2:person} é lido como person. 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 modelosImagens de referência
Família Seedance 2Até 9
HappyHorse Ref2VAté 9
Gemini Omni, Kling 3 Omni, Grok Imagine image-to-videoAté 7
VEO 3.1 Fast e VEO 3.1 LiteAté 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_error e indicam POST /v1/text-to-video para 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 exemplo Natalie 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 describedReferences sem nenhuma connectedReferences, 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 de connectedReferences, 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.
  • referenceVideoCaptions e referenceAudioCaptions, em POST /v1/generate-video e /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] descreve referenceVideoUrls[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 Town vira old-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 (manual e wired-image) são object, person, face, clothes, background, style, pose e texture. Criaturas aceitam creature, anatomy, markings, pose, color e style. Objetos aceitam object, shape, material, color, texture e style. Qualquer outra palavra única passa como foi escrita. Sem papel, vale o defaultRole da entrada.
  • ~lock e ~nolock depois 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 vira 3d-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:

ValorAdicionaUse para
standardInstruções para usar só o que as referências mostram, manter a semelhança e compor as referências juntasComposições a partir de várias referências
multi-personO mesmo, mais regras para nunca alterar nem misturar rostosDois 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.

ChavesSeletorImagemVídeo
shotSize, angle, coverage, composition, vantageEnquadramentoSimSim
posePoseSimSim
compositionEffectEfeitos de composiçãoSimSim
cameraFormatCâmera / películaSimSim
lensLenteSimSim
aperture, shutterSpeed, isoValueConfigurações de exposiçãoSimNão
timeOfDay, lightingStyle, lightingDirection, lightingRatio, colorTemperatureIluminaçãoSimSim
colorLookCor / lookSimSim
atmosphereAtmosferaSimSim
postProcessEfeitos de pós-produçãoSimNão
styleEstiloSimSim
moodClimaSimSim
aestheticEstéticaSimSim
photoGenreGênero fotográficoSimNão
photographerFotógrafoSimNão
renderQualityQualidade de renderizaçãoSimNão
settingCenárioSimSim
eraÉpocaSimSim
backdropFundo de estúdioSimSim
cameraMotionMovimento de câmeraNãoSim
actionFxEfeitos de açãoNãoSim
temporalSpeed, temporalFreeze, temporalDirection, temporalShutterEfeitos temporaisNãoSim
transitionTransiçãoNãoSim
loopSubjectTema de loopNãoSim

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, composition e lightingStyle) 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. colorLook também aceita "palette:<id>", e style aceita "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-catalogs lista os IDs que um pacote adiciona. Esses IDs são aceitos, mas não adicionam redação a direction.

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 prompt chega 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. cameraMotion vem primeiro. Só as chaves de visual vão para a seção [style].
  • Nas rotas de vídeo, style adiciona 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.prompt registra 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 linhas Style: e Avoid: 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 paletaUm painel de inspiração
O que contémUm nome de 1 a 80 caracteres, de 2 a 12 cores como #RRGGBB e uma observação opcional de até 500 caracteresUm nome, uma descrição opcional de até 1.000 caracteres e de 1 a 12 imagens { url, caption? }
Como usardirection.colorLook: "palette:<id>"direction.style: "moodboard:<id>"
O que a execução recebeTodas as cores no prompt, com um nome comum e o código hexadecimalA 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étodoCaminhoCorpo ou parâmetrosO que faz
GET/v1/paletteslimit (de 1 a 100, padrão 50), cursorAs 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/:idNenhumUma paleta.
PATCH/v1/palettes/:idQualquer um de name, colors, descriptionSó os campos que você envia são gravados. description: null limpa a observação.
DELETE/v1/palettes/:idNenhumRetorna { success: true }.
GET/v1/moodboardslimit, cursorOs 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/:idNenhumUm painel de inspiração.
PATCH/v1/moodboards/:idQualquer um de name, description, imagesSó os campos que você envia são gravados. images substitui todas as imagens.
DELETE/v1/moodboards/:idNenhumRetorna { 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ço http ou https que não é localhost nem 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 como cursor para a próxima página. Ele é null na ú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:read para as leituras e de assets:write para 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 MCP list_palettes, save_palette, list_moodboards e save_moodboard. O generate_image do MCP aceita palette_id e moodboard_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

StatusCódigoQuando
400validation_errorpalette: 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.
404direction_not_foundA 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, outerwear e footwear. Há também três chaves de objetos: heldProp (Objeto na mão), material (Material) e animal (Animal). GET /v1/picker-catalogs/person e /styling listam todos os campos e IDs.
  • subject e direction nunca se sobrepõem. As chaves de um e de outro são separadas, então uma escolha nunca adiciona duas cláusulas. pose pertence a direction.
  • customAge é o único número. Envie "age": "age-custom" com "customAge": 34 para uma idade exata em anos. O valor é arredondado e mantido entre 0 e 120.
  • As listas têm limites por chave. jewelry, wardrobeState e distinctiveFeature aceitam 3 IDs. ethnicity, regionalAesthetic, hairColor, eyeColor, lipState, eyeState, skinTexture, hairState, heldProp e material aceitam 2. Todas as outras chaves, inclusive animal, 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-character e POST /v1/generate-creature, subject descreve quem o retrato mostra. A redação vem logo depois de seedPrompt ou description e 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étodoCaminhoO que faz
POST/v1/sessionsCria 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/sessionsAs 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/:idUma sessão.
PATCH/v1/sessions/:idAltera 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/:idExclui 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/itemsO 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/itemsImporta { "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/:jobIdRemove 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/restoreTraz de volta um item removido, para onde ele estava.
POST/v1/sessions/:id/items/moveMove { "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, como generate-image, generate-video, text-to-video, text-to-speech e generate-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 responde 404, e nada é criado nem cobrado. As execuções de um workflow nunca são arquivadas em uma sessão.
  • O session_id da tarefa é definido uma vez, quando a tarefa é criada. Ele aparece em GET /v1/jobs/:id e em GET /v1/jobs.
  • Toda rota que cria uma tarefa também aceita origin, o slug do seu app. A tarefa o guarda em input_data.origin, e GET /v1/jobs?origin= filtra por ele. Um valor que não é um slug responde 400 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/jobs aceita projectId=<id>, as tarefas que uma sessão desse projeto contém agora, e projectId=none, as tarefas que uma sessão sem projeto contém. Ele também aceita inSession=false, as tarefas que nenhuma sessão contém agora (Geral), e inSession=true. Cada tarefa aparece uma só vez, não importa quantas sessões a contenham. withSessions=true acrescenta sessions: [{ id, title, projectId }] a cada tarefa, para uma visão de "tudo neste projeto". projectId não pode ser combinado com inSession=false (400). Esses filtros se combinam com type, status e 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 exigem assets:write, assim como enviar sessionId com 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, switchx e split-into-layers. A finalização em 1080p de um rascunho do Seedance 2.5 no video-upscale tem o preço calculado a partir do rascunho e dos clipes com que ele foi feito. Qualquer outro tipo é um 400 quote_unsupported que os lista.
  • Avatares e SwitchX: o ai-avatar tem 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óprio 400 da execução. O cinematic-avatar tem o preço calculado pela resolução e pela duração exatas, e a Duração automática pelo teto de 15 segundos. O switchx tem 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-video tem o preço calculado com todos os clipes enviados a ela, videoUrl e referenceVideoUrls. 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 } }:

CampoSignificado
identifierO ID de crédito em que a execução é cobrada.
reserveOs créditos que a execução retém quando começa.
expectedOs 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.
adjustmentsUma 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).
warningsUma 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 400 da rota de execução. Um clipe que a execução recusaria recebe o 400 video_too_long dela. Um modelo que esta implantação não oferece recebe o 403 model_not_available da execução, e um nó que ela não oferece a você recebe o 403 node_not_available da 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_disabled quando ela está desligada.
  • Uma imagem que a execução recusaria, como uma grande demais ou ilegível, recebe o próprio 400 da 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_size avisa 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 .data
const { 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" }
      ]
    }
  }
}
CampoSignificado
typeO tipo do nó. Para a maioria dos tipos de nó, ele também é a rota: POST /v1/<type>.
label, category, descriptionComo o editor nomeia e agrupa o nó.
outputTypetext, image, video, audio, data ou none.
creditCostO 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.
estimatetrue 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.
creditRatePara 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.
providersOs IDs de modelo que o nó aceita em provider.
capabilitiesFlags de recursos, como supports-reference-image.
inputSchema.fieldsAs 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:

CampoSignificado
maxDurationSecA duração máxima que o nó aceita.
sparseProvidersModelos com poucas durações de segmento. Um valor entre elas é ajustado para a mais próxima.
providerResolutionsAs resoluções de cada modelo, por exemplo { "minimax-h3": ["2K", "768P"] }.
providerResolutionWireO valor exato a enviar para cada resolução, por exemplo 768P, e não 768p, para o nível mais barato do MiniMax H3.
soundtrackNo 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 i2v

A 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.

CampoTipoSignificado
maker{ id, name }, ausente em um modelo oferecido com a própria marca da instânciaA 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.
logoUrlstring ou nullA 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:

CampoTipoSignificado
defaultResolutionstringO 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.
transparentResolutionstringO único tamanho em que um fundo transparente é renderizado. Uma requisição transparente em outro tamanho é executada, e cobrada, neste tamanho.
backgroundOnlyAtTransparentResolutiontrueO 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:

CampoTipoSignificado
outputFormatsstring[]Os arquivos que o modelo grava (png, jpeg, webp, gif, svg), o padrão primeiro. São os valores que outputFormat aceita.
gifFrameSizenumberCom 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.
svgLevelsstring[]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âmetroValoresFiltra por
kindimage, video ou audioUm tipo de mídia
modePor exemplo, t2i, i2v, t2v, tts, video-analysisUma operação
familyUm fabricante, por exemplo Google ou BytedanceUm fabricante
featuredOnlytrueModelos 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 }
  ]
}
CampoSignificado
nodes.deniedOs tipos de nó que não são oferecidos a você. Salvar ou executar um deles é recusado com 403 node_not_available.
nodes.hiddenFromUsersVazio 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.deniedOs ids de modelo que ninguém nesta implantação recebe. Uma execução de um deles responde 403 model_not_available.
models.restrictedtrue 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.hiddenFromUsersAs 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.
worldsTodos 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[].enabledtrue 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étodoCaminhoO que retorna
GET/v1/picker-catalogsTodos 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/:nodeTypeAs 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/catalogsTodos 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-costs com a chave llm-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, jsonSchema e, opcionalmente, schemaName (até 64 caracteres), llmModel, reasoningEffort, maxRetries, origin, advancedMode, temperature e maxTokens. system aceita até 200.000 caracteres, para caber um vocabulário em que o seu schema escreve. input aceita 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, exclusiveMinimum e description. anyOf e oneOf só são aceitos abaixo da raiz. not, if, then, else, as palavras-chave dependent, $ref externo e combinadores na raiz retornam 400. Um anyOf de ramos required abaixo 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: maxTokens vale em toda chamada e não pode passar do limite do próprio modelo. temperature é ignorado, a menos que você também envie advancedMode: 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 maxRetries padrão e de 32 minutos com o máximo. Aumente o timeout do seu cliente HTTP ou use a forma de tarefa abaixo. O timeoutMs padrão do SDK, de 60 segundos, é curto demais.
  • Erros: 400 validation_error, 400 advanced_mode_unavailable, 401, 402, 500 internal_error, 502 llm_error depois que as novas tentativas se esgotam, 502 advanced_mode_unavailable e 503 provider_unavailable. Veja advancedMode acima para a recusa advanced_mode_unavailable. Mais dois códigos dizem respeito à reserva: 409 job_cancelled e 503 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 seu input. Durante a execução, output_data.stage é analyzing e depois drafting.
  • 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.

Última atualização

Nesta página