O PicassoIA Reference To Video usa o ID de modelo picassoia/picassoia-reference-to-video. Referência para vídeo com áudio, clipes de 1 a 15 segundos e saída em 480p ou 720p.
Como Chamar a API
Envie requisições para https://api.picassoia.com/v1/models/picassoia/picassoia-reference-to-video/predictions com um corpo JSON cujo input siga os parâmetros abaixo.
Configuração
Guarde sua API key no seu servidor, em uma variável de ambiente, e envie-a no cabeçalho Authorization de cada requisição.
export PICASSOIA_API_KEY="pia_sk_…"Parâmetros da Requisição
promptstringObrigatório- PadrãoNenhum
- O que a saída deve mostrar. Até 8000 caracteres.
imagesarray- PadrãoNenhum
- As imagens a editar ou combinar. No prompt, refira-se a elas como image 1, image 2 e assim por diante. De 1 a 9 imagens. É necessário enviar pelo menos um destes campos: images ou video. Uma imagem PNG, JPEG ou WebP, como URL https pública ou como data URL de até 5 MB.
videostring- PadrãoNenhum
- O vídeo a ser usado como base. É necessário enviar pelo menos um destes campos: images ou video. Um vídeo MP4, MOV ou WebM de até 50 MB, como URL https pública.
audiostring- PadrãoNenhum
- O áudio a ser usado como base. Um arquivo MP3, WAV, M4A, AAC, OGG ou FLAC de até 20 MB, como URL https pública.
resolutionstring- Padrão
"480p" - O tamanho da saída. Opções: 480p e 720p.
durationinteger- Padrão
5 - A duração do clipe, em segundos. De 1 a 15.
aspect_ratiostring- Padrão
"match_input_image" / "16:9" - O formato da saída. Quando match_input_image é uma das opções, ela mantém as proporções da imagem de entrada, ou da primeira, se houver várias. Opções: match_input_image, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 e 1:1. Se você não enviar: match_input_image quando video é enviado, 16:9 quando não é.
video_strengthstring- Padrão
"high" - O quanto o clipe segue o vídeo de referência. Opções: high, medium e low. Requer o campo video.
save_audioboolean- Padrão
true - Mantém a faixa de áudio gerada.
seedinteger- PadrãoNenhum
- Defina-a para reproduzir um resultado; omita-a para usar uma aleatória.
enhance_promptboolean- Padrão
true - A Picasso IA reescreve seu prompt para obter um resultado melhor. O seu prompt original continua na entrada.
Modos
O modo depende dos arquivos que você envia com o prompt, se houver. Todos os modos usam o mesmo endpoint.
Requisição de Exemplo
Referência para Vídeo
curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-reference-to-video/predictions \
-H "Authorization: Bearer $PICASSOIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"prompt":"Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.","images":["https://example.com/woman.jpg","https://example.com/cafe.jpg"]}}'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))
const input = {
prompt: "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
images: [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg"
]
}
const created = await fetch(`${API}/models/picassoia/picassoia-reference-to-video/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)
console.log(prediction.output)import os, time, requests
API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}
payload = {"input": {
"prompt": "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
"images": [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg",
],
}}
response = requests.post(f"{API}/models/picassoia/picassoia-reference-to-video/predictions", json=payload, 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"])
print(prediction["output"])Autenticação
Toda requisição precisa de uma API key no cabeçalho Authorization, como token Bearer. Crie chaves na sua conta; a chave completa é exibida uma única vez.
Authorization: Bearer $PICASSOIA_API_KEYFila e Consulta Periódica
Toda previsão passa por três etapas: criá-la, consultá-la até que termine e, depois, ler o resultado.
Enviar
A API responde 201, geralmente em poucos segundos, com a previsão no estado starting, uma estimativa em eta e a URL a consultar em urls.get. Se a previsão falhar imediatamente, por exemplo quando o filtro de segurança recusa a entrada, a resposta continua sendo 201, com a previsão no estado failed e o seu erro.
curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-reference-to-video/predictions \
-H "Authorization: Bearer $PICASSOIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"prompt":"Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.","images":["https://example.com/woman.jpg","https://example.com/cafe.jpg"]}}'const API = 'https://api.picassoia.com/v1'
const headers = {
Authorization: `Bearer ${process.env.PICASSOIA_API_KEY}`,
'Content-Type': 'application/json',
}
const input = {
prompt: "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
images: [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg"
]
}
const created = await fetch(`${API}/models/picassoia/picassoia-reference-to-video/predictions`, {
method: 'POST',
headers,
body: JSON.stringify({ input }),
})
let prediction = await created.json()
if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)
console.log(prediction.id, prediction.status) // api_…, startingimport os, requests
API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}
payload = {"input": {
"prompt": "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
"images": [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg",
],
}}
response = requests.post(f"{API}/models/picassoia/picassoia-reference-to-video/predictions", json=payload, headers=HEADERS)
prediction = response.json()
if not response.ok:
raise RuntimeError(f"{prediction['code']}: {prediction['detail']}")
print(prediction["id"], prediction["status"]) # api_…, starting{
"id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
"model": "picassoia/picassoia-reference-to-video",
"input": {
"prompt": "Image 1, the woman with red hair, walks into Image 2, the cafe, and sits by the window. Soft cafe ambience.",
"images": [
"https://example.com/woman.jpg",
"https://example.com/cafe.jpg"
],
"resolution": "480p",
"duration": 5,
"aspect_ratio": "16:9",
"save_audio": true,
"enhance_prompt": true
},
"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": 60,
"next_poll_in_seconds": 30
}
}Consultar
Consulte urls.get de novo após eta.next_poll_in_seconds: na metade do tempo estimado, quando a estimativa é atingida e, depois, a cada 2 segundos.
# Repeat after eta.next_poll_in_seconds until status is
# succeeded, failed or canceled.
curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
-H "Authorization: Bearer $PICASSOIA_API_KEY"const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))
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()
}import time
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(){
"id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
"status": "processing",
"output": null,
"eta": {
"seconds": 30,
"next_poll_in_seconds": 30
}
}Resultado
Quando status é succeeded, output contém o resultado. Uma previsão failed traz o motivo em error, e uma canceled foi interrompida antes de terminar. Os três estados são finais.
# The last poll holds the result: "output" when "status" is succeeded,
# "error" when it is failed. With jq, just those three fields:
curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
-H "Authorization: Bearer $PICASSOIA_API_KEY" | jq '.status, .output, .error'if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
console.log(prediction.output)if prediction["status"] != "succeeded":
raise RuntimeError(prediction["error"] or prediction["status"])
print(prediction["output"]){
"id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
"status": "succeeded",
"output": "https://…/output.mp4",
"error": null,
"completed_at": "2026-10-01T09:30:54.000Z",
"metrics": {
"predict_time": 52.8
},
"eta": null
}Cancelar
POST urls.cancel interrompe uma previsão que ainda está na fila (qualquer modelo) ou uma imagem que ainda está sendo gerada; um vídeo que já está em geração retorna 409 not_cancelable.
Os IDs, horários e URLs destas respostas são exemplos: os seus terão valores próprios.
Saída
Quando a previsão termina com sucesso, output é a URL de um vídeo MP4.
Erros e Limites
Os erros são respostas JSON no formato problem details, com um code estável, e um 422 indica todos os campos com problema.
Limites
- 5 previsões na fila ou em execução ao mesmo tempo por conta
- Corpo da requisição de até 10 MB; imagens como data URLs de até 5 MB cada
- Prompt de até 8000 caracteres
- Campos desconhecidos são recusados com 422 invalid_input
Preços
$0 por requisição com um plano Infinite ativo: as previsões da API não consomem créditos, sejam quais forem as configurações.
Preços da APIJSON Schema
O mesmo esquema que a API disponibiliza em GET /v1/models/picassoia/picassoia-reference-to-video.
{
"input_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 8000,
"description": "What happens in the video and what is heard. Name the references: \"Image 1\", \"Video 1\", \"Audio 1\"."
},
"images": {
"description": "Up to 9 reference images (characters, objects, places), in the order of \"Image 1\", \"Image 2\"… At least one image or a video is required.",
"maxItems": 9,
"type": "array",
"items": {
"type": "string",
"description": "A reference image: an https URL or a data URL."
}
},
"video": {
"type": "string",
"description": "Reference video: an https URL (MP4, MOV or WebM, up to 50 MB; its first 15 s are used). The clip follows its movement, camera and timing, keeps its sound unless an audio is sent, and lasts as long as the video, or duration if that is shorter. To put your own character in it, say who replaces whom (\"Image 1 replaces the woman in Video 1\") and what they do."
},
"audio": {
"type": "string",
"description": "Reference audio: an https URL (MP3, WAV, M4A, AAC, OGG or FLAC, up to 20 MB). A voice a character says with lip sync (\"Image 1 says Audio 1\"), or music. It is heard as it is. Lip sync is most exact in clips of up to 5 s."
},
"resolution": {
"default": "480p",
"description": "480p or 720p, both up to 15 s.",
"type": "string",
"enum": [
"480p",
"720p"
]
},
"duration": {
"default": 5,
"description": "Length in seconds.",
"type": "integer",
"minimum": 1,
"maximum": 15
},
"aspect_ratio": {
"description": "Default: 16:9, or the reference video's when there is one. match_input_image follows the video if there is one, otherwise the first image.",
"type": "string",
"enum": [
"match_input_image",
"16:9",
"9:16",
"4:3",
"3:4",
"3:2",
"2:3",
"1:1"
]
},
"video_strength": {
"description": "Only with a video: how closely the clip follows it. high (the default) follows its camera, composition and timing most closely; medium and low follow it more loosely and render faster.",
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"save_audio": {
"default": true,
"description": "Keep the generated audio track.",
"type": "boolean"
},
"seed": {
"description": "Random seed. Set it to reproduce a result.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"enhance_prompt": {
"default": true,
"description": "Let PicassoIA rewrite the prompt for a better video before generating it.",
"type": "boolean"
}
},
"required": [
"prompt"
],
"additionalProperties": false
},
"output_schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "string",
"format": "uri",
"description": "URL of the generated video (MP4)."
}
}