Pular para o conteúdo principal

Com filtro — Este modelo recusa de forma clara os pedidos que passam dos seus próprios limites. É um resultado medido, não presumido; modelos que você não vê rotulados ainda não foram medidos.Ver todos os modelos com esse nível de filtragem
kling/o3/reference-to-video

O reference-to-video Kling O3 (Kling 3.0 Omni) reúne até 7 imagens de referência, como uma pessoa, uma roupa ou um lugar, em uma nova tomada. Os clipes têm 3 a 15 segundos em 720p, 1080p ou 4K, com áudio nativo opcional.

A partir de $0.067/s
Executar modelo

Playground

Enviar uma requisição

Início rápido

Os exemplos usam as definições públicas de parâmetros do endpoint selecionado. Troque a chave de API e as mídias de exemplo e envie a requisição a partir do seu servidor.

SDKs e integrações
POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

Autenticação da API

Guarde a chave de API na variável de ambiente do servidor SPICY_API_KEY. Use autenticação Bearer e Content-Type: application/json nas requisições JSON.

Authorization: Bearer $SPICY_API_KEY
Resultado de exemploUsar este exemplo
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "kling/o3/reference-to-video",
  "input": {
    "aspect_ratio": "16:9",
    "duration_seconds": 5,
    "generate_audio": false,
    "prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
    "reference_image_urls": [
      "https://example.com/reference.png"
    ],
    "resolution": "720p",
    "shot_type": "single"
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Gerado a partir do schema de entrada deste modelo — o mesmo que a API usa para validar cada requisição.

Parâmetros de entrada

Coloque estes campos no objeto input do corpo da requisição. Nomes e tipos são os mesmos da API. Quando nenhum valor padrão estiver indicado, não presuma que exista um.

Este modelo tem dependências entre campos. Os campos marcados como obrigatórios sob condição dependem de outras entradas; as regras completas estão no JSON Schema abaixo.

reference_image_urlsarray<string>Obrigatório

Até 7 fotos de referência para personagens, objetos, roupas ou lugares. JPEG ou PNG. Refira-se a cada uma no prompt como <<<image_1>>>, <<<image_2>>> etc.

Valor padrão
Não especificado
Restrições
minItems:1
maxItems:7
promptstringObrigatório

Diga o que cada referência numerada é (<<<image_1>>>, <<<image_2>>> e assim por diante) e descreva a cena que elas devem produzir juntas. Nomear a função de cada foto é o que a impede de se misturar com as outras.

Valor padrão
Não especificado
Restrições
minLength:1
maxLength:2500
multi_promptarray<object>Obrigatório sob condição

A lista de tomadas para shot_type customize: até 6 tomadas em ordem, cada uma com seu próprio prompt (até 512 caracteres) e duração em segundos inteiros. As durações precisam somar duration_seconds, que continua sendo a base da cobrança.

Valor padrão
Não especificado
Restrições
minItems:1
maxItems:6
shot_typestringOpcional

single pede uma tomada contínua única (não é uma garantia rígida). multi deixa o modelo dividir a cena em várias tomadas sozinho. customize segue a lista de tomadas que você passa em multi_prompt. Nenhuma das opções muda o preço.

Valor padrão
"single"
Valores permitidos
"single""multi""customize"
duration_secondsintegerOpcionalAfeta o preço

Segundos inteiros, de 3 a 15. Influencia o preço junto com resolução e áudio.

Valor padrão
5
Restrições
minimum:3
maximum:15
keep_original_audiobooleanOpcional

Mantém no resultado o som original do vídeo de referência. Ligado por padrão; só faz diferença quando você passa um vídeo de referência. Não muda o preço.

Valor padrão
true
generate_audiobooleanOpcionalAfeta o preço

Acrescenta uma trilha sonora gerada na mesma passada — diálogo entre aspas, efeitos, ambiência. Em 720p e 1080p custa mais por segundo do que uma execução silenciosa; em 4K o preço não muda com o som ligado ou desligado. Não está disponível junto com um vídeo de referência.

Valor padrão
false
resolutionstringOpcionalAfeta o preço

720p, 1080p ou 4K. Níveis mais altos custam mais por segundo.

Valor padrão
"720p"
Valores permitidos
"720p""1080p""4k"
aspect_ratiostringOpcional

16:9, 9:16 ou 1:1. Escolha antes de escrever a tomada para que a composição se encaixe.

Valor padrão
"16:9"
Valores permitidos
"16:9""9:16""1:1"
elementsarray<object>Opcional

Um sujeito nomeado para execuções em 4K: dê a ele um nome, uma descrição de uma linha e de 2 a 4 fotos da mesma pessoa ou objeto (amostras de voz de 5 a 30 segundos são opcionais) e depois escreva @nome no prompt ou na lista de tomadas onde o sujeito deve aparecer. Um sujeito por solicitação; ele conta no limite de 7 referências dividido com reference_image_urls. Não muda o preço.

Valor padrão
Não especificado
Restrições
maxItems:1
reference_video_urlsarray<string>OpcionalAfeta o preço

Vídeo de referência opcional, um único clipe, do qual a nova tomada aproveita movimento, câmera ou personagens; cite-o no prompt como <<<video_1>>>. Com vídeo, use até 4 imagens de referência, e generate_audio precisa ficar desligado. Uma execução com vídeo de referência é cobrada a uma taxa por segundo maior do que sem; não está disponível em 4K.

Valor padrão
Não especificado
Restrições
minItems:1
maxItems:1

Acompanhar tarefa

HTTP 202 quer dizer que a tarefa foi aceita, não que terminou. Guarde o taskId devolvido e consulte essa tarefa. Não crie outra enquanto espera o resultado.

Requisição aceita
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_create",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.750000"
  }
}

A resposta de aceitação já traz a estimativa, para que o seu aplicativo mostre o mesmo valor no histórico de tarefas e na cobrança.

Consultar a tarefa
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
  --data-urlencode "taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Comece consultando a cada 2 segundos, mais ou menos, e vá espaçando. Pare em um estado final. Se a conexão cair, consulte o taskId original. Só recrie a tarefa com a chave de idempotência e o corpo originais.

Ou receba o resultado por callback
import { verifyWebhook } from "@spicyapi/sdk";

// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
  const { payload } = verifyWebhook({
    rawBody: req.body,
    timestamp: req.header("X-Webhook-Timestamp"),
    signature: req.header("X-Webhook-Signature"),
    payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
    secret: process.env.SPICY_WEBHOOK_SECRET,
  });
  res.status(200).end();
  void handleFinishedTask(payload);
});

Passe callBackUrl ao criar a tarefa e o registro concluído chega até você via POST — sem nenhum laço de polling. Toda entrega traz X-Webhook-Timestamp, X-Webhook-Signature e X-Webhook-Payload-Version. A assinatura é um HMAC-SHA256 em base64 sobre taskId.timestamp.sha256(body), então confira contra os bytes brutos: se você analisar o JSON e serializar de novo, os bytes mudam e a verificação falha. Entregas com erro são repetidas, ou seja, o mesmo taskId pode chegar duas vezes — deixe seu handler idempotente. Responda 2xx primeiro e faça o trabalho depois; um handler lento conta como entrega falha.

Ler resultado

Só consuma output quando state for succeeded. Em caso de falha, use errorCode, errorMessage e request_id para investigar. Os custos e estados de exemplo não representam uma cobrança real.

Exemplo de resposta concluída
{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_record",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "kling/o3/reference-to-video",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.mp4",
          "mime": "video/mp4",
          "url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T12:20:08.000Z"
        }
      ]
    },
    "cost": "0.750000",
    "settled": true,
    "createdAt": "2026-08-28T12:00:00Z",
    "completedAt": "2026-08-28T12:00:30Z"
  }
}

Para cada arquivo disponível, abra ou baixe assets[].url direto, sem o cabeçalho Authorization da API. O link assinado expira em expiresAt: consulte a tarefa de novo para renovar enquanto o arquivo estiver dentro do prazo de retenção. Arquivo pendente ou indisponível não tem URL. Trate os links assinados como dado privado.

SDKs e integrações

Use a SpicyAPI no seu app, terminal, assistente de IA ou fluxo visual. Escolha um guia de configuração.

SDKs
TypeScript · Python · Go · PHP · Java
CLI
Comandos de terminal e scripts de automação.
MCP
Claude Code · Cursor · Codex
Agent Skill
Instruções reutilizáveis para seu assistente de IA.
n8n
Nós comunitários para instalações próprias e modelos importáveis com HTTP Request para n8n Cloud.
ComfyUI
Fluxos de imagem, vídeo e áudio em um canvas de nós.

Mais integrações

SillyTavernTelegram / DiscordApp proxyOpenAI SDKLangChainVercel AI SDK
Explorar fluxos prontos para usar

Use no ComfyUI

Instale os nós da SpicyAPI pelo ComfyUI Manager ou com o comando abaixo e procure por Kling O3 · Reference to Video no canvas. O nó tem as mesmas opções desta página e mostra o preço antes da execução.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi
Exemplos de fluxos de trabalhoGuia de configuraçãoCódigo-fonte no GitHub