Chave de API do Seedream: acesso gratuito, playground e exemplo em Node.js

Ao digitar Seedream API Key em uma barra de busca, você cai em dois lugares bem diferentes: a plataforma própria da ByteDance e uma série de sites que hospedam o modelo para você. Qual deles você precisa depende do que pretende entregar. Se você só quer ver o que o Seedream produz, não precisa de nenhuma credencial. Se quer um script que envie prompts e salve arquivos, precisa de uma conta com um provedor de API, e os provedores variam muito em preço, limites e acesso aos modelos. Este artigo apresenta cada caminho com fatos conferidos nas páginas oficiais, aponta onde o acesso gratuito termina e inclui um script em Node.js que você pode executar hoje. Vale dizer um resultado logo de início: a API do PicassoIA serve os próprios quatro modelos, e o Seedream não é um deles, então o playground é onde o Seedream fica no PicassoIA.

Dois caminhos para o Seedream

O Seedream é uma família de modelos de imagem da ByteDance, e o mesmo nome de modelo aparece atrás de portas bem diferentes. Antes de copiar qualquer código, escolha a porta que combina com seu objetivo.

Uma regra prática: se o resultado for um punhado de imagens para um post ou uma apresentação, use o playground e pare por aí. Se você está criando um produto cujos usuários acionam o Seedream diretamente, vá ao provedor e planeje a cobrança por uso desde o primeiro dia. Se está automatizando lotes de miniaturas ou edições com os modelos do PicassoIA, a API do PicassoIA serve, desde que seu plano permita. Combinar caminhos é normal: rascunhe no playground e depois leve o prompt vencedor para um script.

O caminho do playground

O jeito mais rápido de começar é pelo navegador. O Seedream 5 Pro transforma um prompt de texto, ou até 10 fotos de referência, em uma imagem de 1K ou 2K. O Seedream 4.5 leva a resolução mais longe, com saída em 2K e 4K de até 4.096 pixels e um modo em lote que devolve até 15 imagens relacionadas em uma única execução. As duas páginas de modelo descrevem a experiência no navegador como gratuita e online, sem precisar programar.

Esse caminho serve para quem itera pelo olho: troca uma expressão de iluminação, gera de novo e compara os dois resultados lado a lado. Não serve para um trabalho que precisa de 500 imagens durante a noite, porque cada geração é um clique manual.

O caminho do provedor direto

A própria página do Seedream 5 Pro cita as orientações da BytePlus, observando que os prompts funcionam melhor com menos de 600 palavras em inglês. A BytePlus mantém o ModelArk, sua plataforma de modelos, e é desse console que sai uma credencial direta do Seedream. Segundo a documentação do ModelArk, contas novas recebem uma cota gratuita de teste de inferência que abate as taxas de inferência cobradas por uso. Essa cota é calculada separadamente para cada modelo e compartilhada na conta principal. A geração de imagens passa pela API de geração de imagens, que expõe um endpoint /images/generations. Documentações de integrações de terceiros listam https://ark.ap-southeast.bytepluses.com/api/v3 como a URL base regional padrão.

💡 Copie o ID exato do modelo ou do endpoint do seu console do ModelArk, não de um blog, nem deste aqui. Os identificadores mudam a cada versão, e um ID desatualizado faz a requisição falhar antes mesmo de chegar ao modelo.

Não estou colocando de propósito um exemplo de código para o provedor direto aqui. A estrutura da requisição e os IDs dos modelos pertencem à BytePlus, mudam, e um palpite errado desperdiça sua tarde. O exemplo em Node.js mais adiante neste artigo usa a API do PicassoIA, onde cada endpoint e campo abaixo vem diretamente da documentação dela.

Acesso gratuito sem nenhuma credencial

O acesso gratuito é real, mas tem limites. Veja o que cada página promete e onde essas promessas param.

O que as páginas dos modelos oferecem

O que grátis não significa

Ser gratuito no navegador não diz nada sobre a API. A página do PicassoIA Image anuncia geração ilimitada de texto para imagem, sem teto por imagem. A documentação da API afirma que as predições são atualmente gratuitas e não usam créditos, mas a mesma documentação exige o plano Infinite, e uma requisição sem ele retorna 403 plan_required.

A página de preços lista o acesso à API em mais de um nível, então as duas páginas redigem isso de formas diferentes. Confira o seu plano antes de construir um produto em cima dele. A mesma cautela vale para as cotas de teste dos provedores: um teste é um saldo inicial, não uma permissão permanente.

Os limites também podem estar ligados à resolução, ao tamanho do lote ou à concorrência, e não a uma contagem fixa de imagens. Leia a tabela de limites na seção da API antes de desenhar um trabalho em lote com base em um número que você viu apenas em uma página de divulgação.

Como usar o Seedream 5 Pro

O Seedream 5 Pro no PicassoIA é rápido de configurar. Siga estes passos na ordem:

1. Abra a página do modelo. Acesse o Seedream 5 Pro e entre na sua conta.
2. Escreva o prompt. O limite é de 4.000 caracteres, mas a BytePlus recomenda ficar abaixo de 600 palavras em inglês.
3. Escolha um tamanho. 1K tem cerca de 2 megapixels e 2K tem cerca de 4 megapixels. O padrão é 2K.
4. Escolha uma proporção. As opções são 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 e 21:9. O padrão, match_input_image, copia a proporção da sua primeira foto de referência.
5. Anexe referências, se tiver. Adicione de 1 a 10 imagens para misturar rostos, objetos ou estilos em um único resultado.
6. Defina o formato de saída e gere. Escolha PNG ou JPEG, execute e baixe o arquivo.

Configurações de prompt que importam

Três configurações mudam os resultados mais do que qualquer adjetivo no prompt:

• Tamanho. Use 1K para rascunhos e 2K para o que você for publicar. Mude para o Seedream 4.5 quando precisar de 4K, porque o Seedream 5 Pro chega no máximo a 2K.
• Quantidade de referências. Mais referências acrescentam consistência, mas também acrescentam restrições. Comece com duas ou três e adicione mais só quando o rosto ou o produto se desviar.
• Proporção. Defina-a explicitamente quando a imagem tiver um destino. Deixar que ela acompanhe uma referência é prático, mas ela herda silenciosamente o enquadramento daquela foto.

💡 Descreva a luz, não o clima. "Sol baixo pela esquerda, sombras longas na calçada" dá ao modelo algo para desenhar. "Atmosfera dramática" não dá nada.

Aqui está um prompt que usa bem essas configurações, escrito para 2K em 16:9: Uma tigela de cerâmica com laranjas sobre um pano de linho ao lado de uma janela, sol baixo da manhã vindo da esquerda, sombras suaves se estendendo pela mesa de madeira, aparência de lente de 85mm, profundidade de campo rasa, a trama do linho visível. Ele nomeia um assunto, uma direção de luz e uma textura de superfície em menos de 50 palavras. O Seedream 5 Pro aceita muito mais, mas um prompt curto e concreto é a melhor base: acrescente um detalhe por execução e mantenha a mudança só se a imagem melhorar.

O caminho da API do PicassoIA

De onde vem a credencial

A API para desenvolvedores do PicassoIA autentica com um segredo Bearer que começa com pia_sk_. Você o cria na sua conta pela página da API do PicassoIA, e cada conta pode ter duas. Trate-o como uma senha: guarde-o em uma variável de ambiente, nunca em um repositório, e troque-o se ele vazar em um print ou em um log.

No Node 20.6 ou mais recente, você pode guardar o segredo em um arquivo .env e carregá-lo com node --env-file=.env generate.mjs, assim ele nunca vai parar no histórico do seu shell. Adicione .env a .gitignore antes do primeiro commit. Se você publicar o script, defina a variável no gerenciador de segredos da sua hospedagem em vez de copiar o arquivo.

Modelos que a API serve

A documentação da API lista quatro modelos:

• PicassoIA Image, slug picassoia/picassoia-image, para texto para imagem
• PicassoIA Image Editor Pro, slug picassoia/picassoia-image-editor-pro, para edição com 1 a 4 imagens de entrada
• PicassoIA Video, slug picassoia/picassoia-video
• Seedance 2.5 Lite, slug picassoia/seedance-2.5-lite, vídeo com áudio

O Seedream não está nessa lista. Se um tutorial mandar você chamar um modelo Seedream com um segredo pia_sk_, confira antes a lista de modelos da sua própria conta.

Plano e limites

Exemplo em Node.js que funciona

Você precisa do Node 18 ou mais recente, que traz um fetch global. Salve o código como generate.mjs, exporte seu segredo como PICASSOIA_SECRET e execute node generate.mjs.

A função auxiliar

Esta função auxiliar segue a documentação oficial, com uma mudança: a variável de ambiente se chama PICASSOIA_SECRET. Ela cria uma predição, espera o intervalo que a API sugere, consulta até a predição chegar a um status final e devolve a saída.

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_SECRET}`,
  'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))

async function run(model, input) {
  const created = await fetch(`${API}/models/${model}/predictions`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ input }),
  })
  let prediction = await created.json()
  if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)

  while (!['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
    await sleep(prediction.eta?.next_poll_in_seconds ?? 2)
    prediction = await (await fetch(prediction.urls.get, { headers })).json()
  }
  if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
  return prediction.output
}

Copiar prompt

Gere sua primeira imagem

Adicione isto ao mesmo arquivo. Ele pede ao PicassoIA Image uma imagem JPEG 16:9 e a grava em disco.

import { writeFile } from 'node:fs/promises'

const output = await run('picassoia/picassoia-image', {
  prompt: 'A weathered fisherman mending a net on a grey pier at dawn, 35mm film look, soft side light',
  aspect_ratio: '16:9',
  num_outputs: 1,
  output_format: 'jpg',
  output_quality: 80,
})

const [url] = [].concat(output)
const image = await fetch(url)
await writeFile('result.jpg', Buffer.from(await image.arrayBuffer()))
console.log('Saved result.jpg from', url)

Copiar prompt

A linha [].concat(output) aceita uma única URL ou uma lista, então o script continua funcionando qualquer que seja o formato da saída.

Edite uma foto existente

O PicassoIA Image Editor Pro precisa de um prompt e de 1 a 4 imagens. A documentação lista data URLs de até 5 MB cada, então leia o arquivo e codifique-o:

import { readFile } from 'node:fs/promises'

const photo = await readFile('portrait.jpg')
const edited = await run('picassoia/picassoia-image-editor-pro', {
  prompt: 'Replace the grey wall with warm red brick, keep the lighting and the face unchanged',
  images: [`data:image/jpeg;base64,${photo.toString('base64')}`],
  aspect_ratio: 'match_input_image',
})
console.log(edited)

Copiar prompt

Erros e limites na prática

Leia o corpo do erro

Quando a criação falha, a função auxiliar lança o code e o detail da própria API, e é por isso que um plano ausente aparece como plan_required em vez de um erro de rede vago. Depois da criação, uma predição passa por cinco status:

Uma predição que falhou não se reinicia sozinha, então uma nova tentativa significa criar outra. Um wrapper simples lida com falhas transitórias e desiste na hora de um erro de plano, que nenhuma espera vai resolver:

async function runWithRetry(model, input, attempts = 3) {
  for (let i = 1; i <= attempts; i++) {
    try {
      return await run(model, input)
    } catch (error) {
      if (i === attempts || String(error.message).startsWith('plan_required')) throw error
      await sleep(i * 5)
    }
  }
}

Copiar prompt

Fique abaixo de cinco predições

O limite é de cinco predições simultâneas por conta, e a contagem é compartilhada entre todas as credenciais e todas as gerações via MCP. Um script em lote e uma sessão de chat aberta puxam do mesmo conjunto de cinco. Um pequeno pool de workers mantém você abaixo do teto e deixa uma vaga livre:

async function pool(tasks, limit = 4) {
  const results = []
  let next = 0
  const worker = async () => {
    while (next < tasks.length) {
      const i = next++
      results[i] = await tasks[i]()
    }
  }
  await Promise.all(Array.from({ length: limit }, worker))
  return results
}

const prompts = ['a red bicycle against a pale wall', 'a lighthouse on a grey coast']
const images = await pool(
  prompts.map((prompt) => () => run('picassoia/picassoia-image', { prompt, aspect_ratio: '16:9' })),
)

Copiar prompt

Adicione um LLM e movimento

Uma imagem raramente é o último passo. Duas outras coleções do PicassoIA se encaixam direto no pipeline: modelos de linguagem antes da imagem, e vídeo depois dela.

Rascunhe prompts com um LLM

Uma ideia de uma linha dá pouco material ao modelo. Cole-a no Claude Sonnet 5 ou no Gemini 3.5 Flash e peça estrutura:

Reescreva esta ideia como um único prompt de imagem de cerca de 120 palavras, com o assunto, o cenário, a direção da luz, a lente e a textura da superfície: "pescador consertando redes ao amanhecer".

Envie o resultado para o Seedream 5 Pro no playground ou para o PicassoIA Image pelo script acima. Os quatro modelos da API listados antes não incluem um modelo de chat, então essa etapa acontece no site.

Anime os resultados

Quando uma imagem fixa estiver boa, o Seedance 2.5 Lite pode usá-la como quadro inicial. A página dele lista clipes de 5 ou 10 segundos em 480p ou 720p, com áudio sincronizado, e descreve geração ilimitada para membros Wonder. O PicassoIA Video aceita a mesma entrada de imagem para vídeo, com duração fixa de 5 segundos e taxa de 24 quadros por segundo (fps). Para visuais estilizados, o PicassoIA também oferece uma categoria de efeitos com centenas de efeitos de vídeo, acessível pela página de todos os modelos.

Descreva o movimento em ordem, como um diretor o chamaria: O pescador puxa a rede em sua direção, a câmera faz uma panorâmica lenta para a direita, gaivotas cruzam o céu pálido, a luz suave se mantém constante. Uma ação do sujeito, um movimento de câmera e uma nota de iluminação bastam para um clipe curto.

Rode seu primeiro prompt do Seedream

Escolha uma ideia, com uma frase, e transforme-a em imagem hoje. Abra o Seedream 5 Pro no PicassoIA, cole um prompt, escolha 2K e 16:9, e gere. Rode o mesmo prompt no Seedream 4.5 em 4K e compare os dois arquivos em tamanho real.

Quando clicar deixar de ser prático, crie uma credencial da API do PicassoIA, cole a função auxiliar acima em um arquivo e envie seus prompts pelo PicassoIA Image. Mude uma variável por execução, guarde os seeds de que gostar e deixe o limite de cinco vagas definir o seu ritmo. Todos os modelos citados aqui estão a um clique na página de todos os modelos.