API de IA para imagem e vídeo na Picasso AI: preços, chave e documentação

Se você pesquisou por uma API da Picasso AI, provavelmente quer três respostas antes de escrever qualquer código: quanto custa, como fazer a autenticação e o que a documentação permite chamar. Resumindo: o PicassoIA roda uma API REST no estilo Replicate em https://api.picassoia.com/v1, autentica com um token bearer que começa com pia_sk_, expõe quatro modelos para imagens e vídeos, e a documentação informa que as predições de API estão gratuitas no momento. O porém é um requisito de plano, e vale a pena ler antes de construir qualquer coisa sobre ele. Este artigo segue a ordem em que você vai encontrar as coisas na prática: preços, configuração de credenciais, sua primeira requisição, os limites, vídeo e o conector MCP, que compartilha os mesmos quatro modelos.

O que a API do PicassoIA oferece

A página da API do PicassoIA descreve uma superfície pequena e focada. Você envia uma requisição para criar uma predição, o trabalho roda nas GPUs próprias do PicassoIA e você consulta até o resultado ficar pronto. Não há SDKs para instalar, e os exemplos de código da documentação usam HTTP simples em cURL, Python e Node.

URL base e autenticação

Cada chamada vai para uma única URL base e carrega um único cabeçalho:

Base URL:      https://api.picassoia.com/v1
Header:        Authorization: Bearer pia_sk_...
Content-Type:  application/json

Copiar prompt

O prefixo pia_sk_ marca um token secreto. Trate-o como uma senha, porque quem o tiver pode consumir a capacidade do seu plano.

Os quatro modelos

O catálogo web lista mais de 250 modelos de imagem, vídeo e chat. A API expõe quatro deles:

💡 Vale saber: a referência da API também oferece GET /v1/models, que retorna todos os modelos com o esquema de entrada de cada um. Leia uma vez em vez de adivinhar nomes de parâmetros a partir dos exemplos.

Endpoints em resumo

Para quem esta API serve

Quatro modelos e cinco vagas servem a um tipo específico de projeto. Ela funciona bem para pipelines de conteúdo que transformam uma planilha de nomes de produtos em banners, para pequenos apps que adicionam um botão de "criar uma imagem", para equipes editoriais que precisam de um fluxo constante de imagens de cabeçalho e loops curtos de vídeo, e para scripts que rodam durante a noite enquanto ninguém espera. Ela serve menos bem quando você precisa de um modelo de terceiros específico, de um endpoint de chat ou de centenas de usuários simultâneos, porque o teto é por conta e a lista de modelos é fixa.

Preços da API e requisitos de plano

Predições gratuitas, com um porém

A documentação diz com clareza: "As predições de API estão atualmente gratuitas. Elas não usam créditos." Isso elimina a conta habitual por chamada. A maioria das APIs hospedadas de imagem e vídeo cobra por chamada ou por segundo de saída, então um bug que entra em loop custa dinheiro. Aqui, o mesmo bug custa vazão, por causa do teto de cinco predições descrito abaixo.

O porém está no plano. De acordo com a referência da API, um plano Infinite é necessário para criar predições. Ler, listar e cancelar funcionam sem ele, então você pode testar seu token e o código do cliente em um plano inferior, mas a primeira POST que cria um trabalho exige o Infinite.

Lendo a página de preços

A página de preços traz um segundo sinal. Ela lista API Access e MCP Connections como recursos dos planos pagos (Pro+, Elite e Infinite), cada um com um selo "New", mas não diz nada sobre as chamadas de API consumirem créditos. Assim, você tem duas afirmações que não se alinham por completo:

💡 Regra prática: trate a página da API como a fonte de referência para criar predições e confirme na sua própria conta antes de prometer qualquer coisa a um cliente. Os preços dos planos mudam, então consulte o preço atual do Infinite na página de preços em vez de confiar em um número copiado para um artigo.

Como a palavra "atualmente" aparece na documentação, construa sua integração de modo que um custo possa ser adicionado depois: registre cada ID de predição, modelo e tamanho de saída desde o primeiro dia. Se a cobrança um dia chegar, você já terá os dados de uso.

Crie e proteja sua credencial

Crie um token na sua conta

1. Entre no PicassoIA e abra a seção de API da sua conta.
2. Crie um novo token. Ele começa com pia_sk_.
3. Copie-o imediatamente. Ele é mostrado apenas uma vez, na criação, e não pode ser recuperado depois, então um token perdido significa criar outro.
4. Guarde-o em um gerenciador de senhas ou em um cofre de segredos antes de fechar a janela.

Cada conta pode ter no máximo 2 tokens. Esse limite parece apertado, mas combina com um hábito de rotação limpa, explicado a seguir.

Mantenha-o fora do seu código

Coloque o token em uma variável de ambiente e leia-o em tempo de execução. Os exemplos abaixo usam PICASSOIA_API_TOKEN, um nome escolhido para este artigo, não um nome exigido pela plataforma.

• Apenas no servidor. Nunca envie o token no JavaScript do navegador ou em um app móvel. Qualquer pessoa pode lê-lo na aba de rede.
• Rotacione com a segunda vaga. Crie o token dois, implante-o, confirme que o tráfego funciona e então revogue o token um. Você nunca fica sem acesso.
• Nunca faça commit dele. Adicione .env ao seu arquivo de ignorados e revise commits antigos se um dia você tiver vazado o token.
• Use um token por ambiente quando possível: produção em uma vaga, staging na outra.

Sua primeira requisição, passo a passo

💡 Antes de copiar qualquer coisa: a API segue o padrão do Replicate, então os exemplos usam os nomes de campos que esse padrão implica (id, status, output). Imprima a primeira resposta que você receber e confira esses nomes antes de colocar isso em produção.

Envie a predição

export PICASSOIA_API_TOKEN="pia_sk_your_token_here"

curl -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions \
  -H "Authorization: Bearer $PICASSOIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "a lighthouse at sunset", "aspect_ratio": "16:9"}}'

Copiar prompt

A chamada retorna rapidamente com um objeto de predição. A imagem ainda não existe: o trabalho entra na fila e roda de forma assíncrona.

Consulte até terminar

curl https://api.picassoia.com/v1/predictions/PREDICTION_ID \
  -H "Authorization: Bearer $PICASSOIA_API_TOKEN"

Copiar prompt

Repita a cada poucos segundos até o status mostrar succeeded ou failed. Uma falha é definitiva, então reenvie com uma nova predição em vez de esperar. Quando der certo, a saída traz as URLs das imagens. Salve os arquivos que importam no seu próprio armazenamento em vez de linkar diretamente as URLs de resultado.

Registre o corpo completo da resposta sempre que uma predição falhar, junto com o prompt e o ID do modelo. A maioria das falhas vem de um prompt longo demais, de uma imagem grande demais ou de um objeto input malformado, e a resposta salva mostra qual em segundos. Adicione um timeout rígido próprio, por exemplo dois minutos para uma imagem e dez para um vídeo, e depois chame o endpoint de cancelamento para que um trabalho travado não ocupe uma das suas cinco vagas.

Versões em Python e Node

import os, time, requests

BASE = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_TOKEN']}"}

def generate(prompt):
    r = requests.post(
        f"{BASE}/models/picassoia/picassoia-image/predictions",
        json={"input": {"prompt": prompt, "aspect_ratio": "16:9"}},
        headers=HEADERS,
        timeout=30,
    )
    r.raise_for_status()
    prediction = r.json()

    while prediction["status"] not in ("succeeded", "failed", "canceled"):
        time.sleep(3)
        prediction = requests.get(
            f"{BASE}/predictions/{prediction['id']}", headers=HEADERS, timeout=30
        ).json()
    return prediction

Copiar prompt

const BASE = "https://api.picassoia.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_API_TOKEN}`,
  "Content-Type": "application/json",
};

export async function generate(prompt) {
  const res = await fetch(`${BASE}/models/picassoia/picassoia-image/predictions`, {
    method: "POST",
    headers,
    body: JSON.stringify({ input: { prompt, aspect_ratio: "16:9" } }),
  });
  let prediction = await res.json();

  while (!["succeeded", "failed", "canceled"].includes(prediction.status)) {
    await new Promise((r) => setTimeout(r, 3000));
    prediction = await (await fetch(`${BASE}/predictions/${prediction.id}`, { headers })).json();
  }
  return prediction;
}

Copiar prompt

Limites que moldam seu projeto

Cinco predições ao mesmo tempo

O teto é por conta, não por token. Se um cron job, um app web e uma sessão MCP rodarem juntos, todos puxam das mesmas cinco vagas. Coloque um limitador na frente do seu cliente, como um semáforo ou um pool de cinco workers, e enfileire o restante por conta própria.

A vazão é fácil de estimar. Se uma predição de imagem leva N segundos do envio até succeeded, cinco vagas dão cerca de 5 / N imagens por segundo, e um lote de 500 imagens leva aproximadamente 500 × N / 5 segundos. Meça N nas suas primeiras dez chamadas e dimensione os lotes noturnos com base nesse número, não em um palpite. Trabalhos de vídeo demoram mais, então rode-os em uma fila própria e mantenha uma ou duas vagas livres para imagens.

Três erros aparecem repetidamente:

• Disparar um lote inteiro de uma vez. Cinquenta chamadas POST simultâneas significam quarenta e cinco recusadas ou travadas.
• Esquecer as sessões MCP. Um colega gerando imagens pelo conector consome parte das suas cinco vagas.
• Tentar de novo imediatamente após uma falha. Espere alguns segundos para não lotar as vagas com tentativas fadadas ao fracasso.

Limites de tamanho e de prompt

Um prompt pode ter até 4.000 caracteres, espaço suficiente para os prompts longos e detalhados que o trabalho fotorrealista exige. A restrição mais apertada é a entrada de imagens. Cada imagem em data URL pode chegar a 5 MB, mas o corpo inteiro da requisição para em 10 MB, então quatro imagens quase no limite em uma única chamada de edição não cabem. Reduza a largura para um tamanho razoável e comprima em JPEG antes de codificar.

Vídeo pela API

Configurações do PicassoIA Video

O PicassoIA Video aceita texto ou uma imagem e retorna um único MP4. A referência vincula a duração máxima à resolução:

Escolha a menor resolução que atenda ao briefing. Um rascunho em 480p dá quatro vezes a duração de uma renderização em 1080p, o que combina com loops para redes sociais e storyboards. Trabalhos de vídeo demoram mais que os de imagem, então consulte a cada 8 a 10 segundos, e não a cada 3.

Seedance 2.5 Lite com áudio

O Seedance 2.5 Lite adiciona áudio sincronizado ao clipe, o que poupa uma etapa separada de som. A referência da API lista durações de 5, 10 e 15 segundos, enquanto o catálogo web descreve clipes de até 10 segundos, então leia o esquema de GET /v1/models antes de fixar no código um valor permitido. O maior Seedance 2.5 continua no catálogo do navegador e não faz parte da API.

MCP e modelos de chat ao lado da API

O conector MCP oferece aos assistentes de IA os mesmos quatro modelos, sem nenhum código HTTP. O conector do claude.ai expõe ferramentas para gerar imagens, editar imagens, criar vídeos com qualquer um dos dois modelos de vídeo e gerenciar trabalhos: generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, list_generations, list_models, get_account e cancel_generation.

O fluxo espelha o REST. Uma ferramenta de geração retorna um ID de predição e um tempo estimado assim que uma GPU aceita o trabalho. Depois você chama get_generation após o atraso sugerido e de novo a cada atraso que ela retornar, até o status ser succeeded ou failed. cancel_generation interrompe um trabalho que ainda não começou a renderizar. A concorrência é a mesma, as cinco vagas compartilhadas.

Os modelos de chat são outro assunto. Nenhum dos quatro modelos da API escreve texto, então os modelos de linguagem ficam no navegador: Claude Sonnet 5 para rascunhos longos, GPT 5.6 Sol para problemas difíceis de programação e Gemini 3.5 Flash quando a velocidade importa. Um bom fluxo é criar e refinar um prompt com um deles e depois colar o resultado na sua chamada de API. Modelos como GPT Image 2, Flux 2 Pro, Veo 3.1 e Kling v3 Video também existem apenas no catálogo do navegador.

Como usar o PicassoIA Image na plataforma

Teste cada prompt no navegador antes de automatizá-lo. Um prompt ruim não custa nada ali, e as mesmas ideias passam direto para a chamada de API.

1. Abra a página do PicassoIA Image e entre na sua conta.
2. Escreva o prompt nesta ordem: sujeito e ação, cenário, luz, câmera e lente, detalhes de textura.
3. Escolha a proporção. 16:9 serve para banners e cabeçalhos de blog, 1:1 serve para cards de produto. A API aceita o mesmo campo aspect_ratio.
4. Defina a quantidade de imagens como 1 ou 2, que é a faixa aceita pela API.
5. Gere e então revise o resultado em tamanho real, olhando mãos, bordas e qualquer texto estranho.
6. Envie a melhor imagem para o PicassoIA Image Editor Pro para corrigir um detalhe ou combiná-la com até três outras imagens.

Pronto para testar por conta própria? Abra o PicassoIA Image, escreva o prompt que você enviaria na sua primeira chamada de API e veja-o ser renderizado. Quando o resultado estiver do jeito certo, copie o mesmo prompt para o exemplo de cURL acima e deixe o seu código fazer o resto. Se quiser explorar tudo o que a plataforma pode fazer, o catálogo completo de modelos está a um clique de distância.