Referência da API da PicassoIA

A API da PicassoIA permite executar os modelos de imagem e vídeo da PicassoIA a partir do seu próprio código:

1. Você cria uma previsão para um modelo.
2. Você consulta a previsão periodicamente até que ela termine.
3. Você lê as URLs de saída.

• URL base: https://api.picassoia.com/v1
• Formato: requisições e respostas em JSON, UTF-8.
• Preço: atualmente, as previsões pela API são gratuitas. Elas não consomem créditos.
• Quem pode usar: contas com o plano Infinite.

Sumário

• Autenticação
• Início rápido
• Modelos
• Endpoints
• O objeto de previsão
• Consulta periódica e ETA
• Cancelamento
• Erros
• Limites

Autenticação

Toda requisição precisa de uma API key no cabeçalho Authorization:

Authorization: Bearer pia_sk_…

• Criar uma chave. Crie chaves em picassoia.com, na seção de API keys da sua conta.
  • A chave completa é exibida uma única vez, no momento em que você a cria. Guarde-a em um lugar seguro.
  • Uma conta pode ter 2 chaves ao mesmo tempo. Para abrir espaço, revogue uma delas.
• Revogar uma chave. Uma chave revogada deixa de funcionar imediatamente.
• Mantenha as chaves no servidor. Qualquer pessoa com uma chave pode executar previsões na sua conta, então nunca coloque uma chave em uma página web ou em um aplicativo móvel. A API não envia cabeçalhos CORS, portanto os navegadores não podem chamá-la diretamente.
• Mudanças de plano. As chaves continuam existindo se o seu plano mudar. Sem um plano Infinite, criar previsões retorna 403 plan_required. Ler, listar e cancelar as suas previsões continua funcionando.

Início rápido

1. Crie uma previsão:

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

A resposta (201 Created) é uma previsão no estado starting:

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "model": "picassoia/picassoia-image",
  "input": {
    "prompt": "a lighthouse at sunset, oil painting",
    "aspect_ratio": "16:9",
    "num_outputs": 1,
    "output_format": "jpg",
    "output_quality": 80
  },
  "output": null,
  "error": null,
  "status": "starting",
  "created_at": "2026-10-01T09:30:00.000Z",
  "started_at": null,
  "completed_at": null,
  "metrics": { "predict_time": null },
  "urls": {
    "get": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
    "cancel": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60/cancel"
  },
  "eta": { "seconds": 12, "next_poll_in_seconds": 6 }
}

2. Consulte-a periodicamente (aguarde eta.next_poll_in_seconds entre as chamadas) até que status seja succeeded, failed ou canceled:

curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
  -H "Authorization: Bearer $PICASSOIA_API_KEY"

3. Leia a saída:

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "status": "succeeded",
  "output": ["https://…/lighthouse.jpg"],
  "metrics": { "predict_time": 6.4 },
  "eta": null
}

(Os demais campos foram omitidos aqui.)

Node.js (fetch)

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_API_KEY}`,
  '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
}

const video = await run('picassoia/seedance-2.5-lite', {
  prompt: 'a paper boat sailing down a rainy street',
  duration: 5,
})
console.log(video) // "https://…/video.mp4"

Python (requests)

import os, time, requests

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

def run(model, input):
    response = requests.post(f"{API}/models/{model}/predictions", json={"input": input}, headers=HEADERS)
    prediction = response.json()
    if not response.ok:
        raise RuntimeError(f"{prediction['code']}: {prediction['detail']}")
    while prediction["status"] not in ("succeeded", "failed", "canceled"):
        time.sleep((prediction.get("eta") or {}).get("next_poll_in_seconds", 2))
        prediction = requests.get(prediction["urls"]["get"], headers=HEADERS).json()
    if prediction["status"] != "succeeded":
        raise RuntimeError(prediction["error"] or prediction["status"])
    return prediction["output"]

images = run("picassoia/picassoia-image-editor-pro", {
    "prompt": "put the cat from image 1 on the sofa from image 2",
    "images": ["https://example.com/cat.png", "https://example.com/sofa.jpg"],
})
print(images)  # ["https://…/result.webp"]

Modelos

O esquema exato de cada modelo também é disponibilizado como JSON Schema: GET /v1/models/{owner}/{name} retorna input_schema (com todos os campos, seus limites e valores padrão) e output_schema.

Imagens como entrada. Os campos de imagem aceitam qualquer um destes dois tipos de valor:

• uma URL https acessível publicamente;
• uma data URL: data:image/png;base64,…, e também image/jpeg ou image/webp, de até 5 MB cada.

As imagens devem ser PNG, JPEG ou WebP. A PicassoIA armazena uma cópia própria de cada uma, então o input da previsão mostra a URL dessa cópia. Use URLs para qualquer imagem maior que algumas centenas de KB: o corpo inteiro da requisição é limitado a 10 MB.

Campos desconhecidos são recusados, para que um erro de digitação não faça a API recorrer silenciosamente a um valor padrão. A resposta é 422 invalid_input.

picassoia/picassoia-image

Saída: uma lista de 1 ou 2 URLs de imagem.

picassoia/picassoia-image-editor-pro

Saída: uma lista de 1 ou 2 URLs de imagem.

picassoia/picassoia-video

Saída: uma URL de MP4 (uma string).

picassoia/seedance-2.5-lite

Saída: uma URL de MP4 (uma string).

Endpoints

Modelo

{
  "id": "picassoia/seedance-2.5-lite",
  "owner": "picassoia",
  "name": "seedance-2.5-lite",
  "title": "Seedance 2.5 Lite",
  "description": "Text or image to video with synchronized audio: …",
  "input_schema": { "type": "object", "properties": { "…": {} }, "required": ["prompt"], "additionalProperties": false },
  "output_schema": { "type": "string", "format": "uri" }
}

Criar uma previsão

POST /v1/models/{owner}/{name}/predictions com o corpo { "input": { … } }.

• A API responde assim que o modelo aceita o trabalho, geralmente em poucos segundos, com a previsão no estado starting. Ela nunca espera pelo resultado.
• Se a previsão falhar imediatamente, a resposta continua sendo 201, com a previsão no estado failed e o seu error. Isso acontece, por exemplo, quando a entrada é recusada pelo filtro de segurança.
• Se nenhuma previsão tiver sido criada, a resposta é um erro: entrada inválida, plano, previsões demais em andamento, serviço indisponível.

Listar previsões

GET /v1/predictions retorna as suas previsões da API, 50 por página, das mais recentes para as mais antigas, considerando todas as suas chaves.

• next é a URL da próxima página (…/v1/predictions?cursor=…), ou null na última página.
• previous é sempre null.
• As previsões que você excluiu em picassoia.com não são incluídas.

Uma previsão fica visível por meio de qualquer uma das suas chaves, e nunca para outras pessoas.

O objeto de previsão

Estados.

A distinção entre starting e processing é uma estimativa, feita a partir da posição na fila no momento da criação. Uma previsão nova está sempre em starting. Os três últimos estados são finais: uma previsão em um deles nunca mais muda.

Erros de uma previsão com falha. O error de uma previsão com falha é uma destas mensagens:

• A entrada ou a saída foi recusada pelo filtro de segurança. A mensagem termina em (SAFETY_CHECKER_PICASSO_FILTER_S4).
• The prediction failed. You can try again.
• The prediction timed out. You can try again. A previsão não foi concluída em até 3 horas.

Saídas. As URLs de saída são hospedadas pela PicassoIA. Baixe os arquivos que você quiser manter.

Consulta periódica e ETA

eta.next_poll_in_seconds indica quando vale a pena fazer a próxima consulta:

1. Na metade do tempo estimado.
2. Quando a estimativa é atingida.
3. Depois, a cada 2 segundos.

Exemplo com uma estimativa de 10 s: consulte após 5 s, depois após 10 s e, então, a cada 2 s. Consultar com mais frequência não traz o resultado mais cedo.

Cancelamento

POST /v1/predictions/{id}/cancel:

Uma previsão cancelada libera imediatamente o lugar que ocupava entre as suas 5 previsões em andamento.

Erros

Os erros são respostas JSON no formato problem details, acrescidas de um code estável para uso em programas:

{
  "title": "Too many predictions in progress",
  "detail": "This account can have up to 5 predictions queued or running at once, shared by its API keys and MCP connections, and 5 are. Wait for one to finish and try again.",
  "status": 429,
  "code": "concurrency_limit",
  "retry_after": 10,
  "limit": 5,
  "running": 5
}

invalid_fields. Uma resposta 422 lista todos os campos com problema:

{
  "title": "Input validation failed",
  "status": 422,
  "code": "invalid_input",
  "detail": "input.duration: At 720p the longest clip is 10 seconds.",
  "invalid_fields": [
    { "type": "invalid_value", "field": "input.duration", "description": "At 720p the longest clip is 10 seconds." }
  ]
}

Limites