Guia de Início Rápido da API Kling V3.0 4K

O Kling V3.0 4K está disponível na Novita AI como dois endpoints de API dedicados: kling-v3.0-4k-t2v para texto-para-vídeo e kling-v3.0-4k-i2v para imagem-para-vídeo. Ambos produzem saída nativa de 3840×2160, suportam durações de 3 a 15 segundos e seguem o mesmo padrão de tarefa assíncrona usado em todas as APIs de vídeo da Novita. Se você já tem o Kling V3.0 Standard ou Pro no seu pipeline, mudar para o nível 4K é uma alteração de uma linha no ID do modelo.

Este guia cobre apenas os endpoints específicos do 4K. Para geração de áudio nativa, composição de múltiplas tomadas ou preços por segundo Standard/Pro, consulte a visão geral do lançamento do Kling 3.0 na Novita AI.

Quando Usar o Kling V3.0 4K vs Standard e Pro

O nível 4K faz sentido quando a resolução de saída é a restrição — ativos com qualidade de impressão, exibição em telas grandes ou fluxos de trabalho downstream que exigem quadros de origem de alta resolução para composição ou corte.

Ele não substitui o Standard ou Pro para todos os casos de uso. A iteração e o teste de prompts são mais baratos em resoluções mais baixas, e a geração 4K leva mais tempo por tarefa. Um fluxo de trabalho prático é iterar com o Standard e depois mudar para kling-v3.0-4k-t2v ou kling-v3.0-4k-i2v para o prompt final aceito.

Use kling-v3.0-4k-t2v quando:

• A cena for totalmente descritível em um prompt
• Não houver uma imagem de referência ou ela não for relevante

Use kling-v3.0-4k-i2v quando:

• Um primeiro quadro específico deve ancorar o clipe gerado
• Você precisar de uma aparência consistente do assunto a partir de uma imagem de origem

Passo 1: Obtenha Sua Chave de API da Novita AI

Cadastre-se em novita.ai e gere uma chave de API no painel. Novas contas incluem créditos gratuitos. Armazene a chave como uma variável de ambiente — não a codifique diretamente em arquivos de origem.

export NOVITA_API_KEY="sua_chave_api_aqui"

Passo 2: IDs de Modelo e Endpoints

Modo	ID do Modelo	Endpoint
Texto-para-Vídeo	kling-v3.0-4k-t2v	POST https://api.novita.ai/v3/async/kling-v3.0-4k-t2v
Imagem-para-Vídeo	kling-v3.0-4k-i2v	POST https://api.novita.ai/v3/async/kling-v3.0-4k-i2v
Recuperação de resultado	—	GET https://api.novita.ai/v3/async/task-result?task_id=<id>

Ambos os endpoints aceitam JSON, exigem um token Bearer no cabeçalho Authorization e retornam um task_id imediatamente. O vídeo real é recuperado separadamente do endpoint de resultado da tarefa.

Referências oficiais da API:

• Documentação do Kling v3.0 4K T2V
• Documentação do Kling v3.0 4K I2V

Passo 3: Envie Sua Primeira Requisição

curl -X POST https://api.novita.ai/v3/async/kling-v3.0-4k-t2v \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Um farol solitário em uma costa rochosa durante a hora dourada, plano aberto cinematográfico, ondas quebrando",
    "negative_prompt": "borrado, baixa qualidade, distorcido",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5
  }'

A resposta retorna um task_id:

{
  "task_id": "t2v-kling-4k-abc123"
}

Armazene esse ID — você precisará dele para recuperar o resultado.

Passo 4: Consulte o Resultado do Vídeo

curl "https://api.novita.ai/v3/async/task-result?task_id=t2v-kling-4k-abc123" \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Uma tarefa concluída retorna um objeto task com status: "TASK_STATUS_SUCCEED" e um array videos:

{
  "task": {
    "task_id": "t2v-kling-4k-abc123",
    "status": "TASK_STATUS_SUCCEED"
  },
  "videos": [
    {
      "video_url": "https://...",
      "video_url_ttl": 3600,
      "video_type": "mp4"
    }
  ]
}

Valores de status típicos: TASK_STATUS_QUEUED, TASK_STATUS_PROCESSING, TASK_STATUS_SUCCEED, TASK_STATUS_FAILED. Construa seu loop de consulta em torno desses valores — não presuma um tempo de espera fixo, pois a geração 4K leva mais tempo que 1080P.

Passo 5: Requisição de Imagem-para-Vídeo

O endpoint de imagem-para-vídeo requer uma image_url além do prompt. A imagem define o primeiro quadro; o modelo gera movimento a partir dela.

curl -X POST https://api.novita.ai/v3/async/kling-v3.0-4k-i2v \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "O feixe do farol varre o nevoeiro, movimento lento e dramático",
    "negative_prompt": "cortes rápidos, tremor, baixa qualidade",
    "image_url": "https://seu-armazenamento.exemplo.com/farol-frame.jpg",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5
  }'

Requisitos da imagem (verifique os limites atuais na referência da API Novita):

• Formatos: .jpg, .jpeg, .png
• Tamanho máximo do arquivo: 10 MB
• Dimensões mínimas: 300×300 pixels

A etapa de recuperação do resultado é idêntica ao T2V — consulte /v3/async/task-result com o task_id retornado.

Exemplos em Python

T2V — texto para vídeo 4K

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_t2v(prompt: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
    payload = {
        "prompt": prompt,
        "negative_prompt": "borrado, baixa qualidade",
        "duration": duration,
        "aspect_ratio": aspect_ratio,
        "cfg_scale": 0.5,
    }
    resp = requests.post(
        f"{BASE_URL}/v3/async/kling-v3.0-4k-t2v",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]

def poll_result(task_id: str, interval: int = 10, max_wait: int = 600) -> dict:
    deadline = time.time() + max_wait
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            headers=HEADERS,
            params={"task_id": task_id},
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Tarefa falhou: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Tarefa {task_id} não foi concluída em {max_wait}s")

if __name__ == "__main__":
    task_id = submit_t2v(
        prompt="Um farol solitário em uma costa rochosa durante a hora dourada, plano aberto cinematográfico",
        duration=5,
        aspect_ratio="16:9",
    )
    print(f"Tarefa enviada: {task_id}")
    result = poll_result(task_id)
    video_url = result["videos"][0]["video_url"]
    print(f"Vídeo pronto: {video_url}")

I2V — imagem para vídeo 4K

def submit_i2v(
    prompt: str,
    image_url: str,
    duration: int = 5,
    aspect_ratio: str = "16:9",
) -> str:
    payload = {
        "prompt": prompt,
        "negative_prompt": "borrado, baixa qualidade",
        "image_url": image_url,
        "duration": duration,
        "aspect_ratio": aspect_ratio,
        "cfg_scale": 0.5,
    }
    resp = requests.post(
        f"{BASE_URL}/v3/async/kling-v3.0-4k-i2v",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]

Use a mesma função poll_result para recuperar o vídeo gerado.

Parâmetros Principais

Parâmetro	Tipo	Obrigatório	Observações
prompt	string	Sim	Descrição da cena. Seja específico: assunto, movimento, ângulo de câmera, iluminação.
negative_prompt	string	Não	O que suprimir: borrão, tremor, artefatos, estilos indesejados.
duration	integer	Não	Segundos de vídeo. Faixa: 3–15. O padrão varia — consulte a documentação.
aspect_ratio	string	Não	"16:9", "9:16", "1:1". Padrão: "16:9".
cfg_scale	float	Não	Força de aderência ao prompt. 0.5 é um valor inicial seguro.
image_url	string	Apenas I2V	Imagem do primeiro quadro. Deve ser uma URL publicamente acessível.

Resolução e duração vs. custo

A geração 4K custa mais por segundo que o Standard ou Pro. Antes de se comprometer com um lote completo:

• Teste prompts com kling-v3.0-std-t2v em duration: 3
• Mude para kling-v3.0-4k-t2v apenas para prompts aceitos
• Use duration: 5 para a maioria das saídas; reserve 10–15 segundos para clipes principais

Preços e Estimativas de Custo

A Novita AI usa faturamento por segundo para o Kling V3.0 4K. O preço do nível 4K é mais alto que o Standard ou Pro — verifique novita.ai/models/kling/kling-v3.0-4k-t2v e novita.ai/models/kling/kling-v3.0-4k-i2v para taxas atuais por segundo antes de executar lotes em produção.

Para contexto sobre os níveis Standard e Pro, a visão geral do lançamento do Kling 3.0 documenta as taxas por segundo para esses níveis. O nível 4K tem preço separado.

Padrão de estimativa de custo para qualquer modelo por segundo:

• Determine a duração por clipe (ex.: 5 segundos)
• Multiplique pela taxa por segundo
• Multiplique pelo número esperado de clipes aceitos
• Adicione uma margem de retentativa (10–20% para falhas de prompt)

Solução de Problemas

task_id recebido, mas o resultado nunca é bem-sucedido Tarefas 4K levam mais tempo que equivalentes 1080P. Estenda seu tempo limite de consulta para pelo menos 10 minutos (max_wait=600). Se a tarefa permanecer em TASK_STATUS_PROCESSING além disso, verifique a página de status da Novita ou tente a requisição novamente.

TASK_STATUS_FAILED sem detalhes As causas mais comuns são: prompt contendo conteúdo não permitido, uma image_url inválida ou inacessível no modo I2V, ou um valor de duração fora da faixa suportada. Valide as entradas e tente novamente com um prompt mais simples.

Imagem I2V rejeitada Verifique se a imagem está publicamente acessível por meio de uma URL direta (sem redirecionamento ou parede de autenticação), o formato é .jpg/.jpeg/.png, o arquivo tem menos de 10 MB e as dimensões são de pelo menos 300×300 pixels.

Resolução de saída inesperada Os endpoints 4K têm como alvo 3840×2160. Se seu player ou ferramenta downstream estiver reportando uma resolução menor, verifique se está decodificando o arquivo corretamente. A saída codificada da API deve ser 4K nativa.

Erros de limite de taxa A Novita AI aplica limites de taxa por chave de API. Para cargas de trabalho em lote de alta taxa de transferência, verifique a documentação de limites de taxa e considere enviar tarefas sequencialmente ou com um pequeno atraso entre as requisições.

FAQ

Qual resolução o kling-v3.0-4k-t2v produz?

Ambos os endpoints 4K produzem saída nativa de 3840×2160 (4K UHD). Isso é uma renderização de hardware — não um upscale de uma resolução inferior.

Como o Kling V3.0 4K difere do V3.0 Standard e Pro?

Standard e Pro geram saída 1080P. Os endpoints 4K adicionam resolução nativa de 3840×2160. Standard é o mais rápido e barato; Pro adiciona qualidade visual superior a um custo moderado; 4K é a opção de maior resolução e tem preço correspondente. A duração (3–15 segundos) e a forma da API assíncrona são as mesmas em todos os três níveis.

Posso usar os endpoints 4K com a mesma chave de API do Standard e Pro?

Sim. Todos os endpoints do Kling V3.0 na Novita AI usam a mesma autenticação de token Bearer. A única mudança entre os níveis é o ID do modelo e o caminho do endpoint.

O Kling V3.0 4K suporta geração de áudio nativa?

O sinalizador padrão de co-geração de áudio disponível nos endpoints Standard e Pro do V3.0 também pode ser suportado no nível 4K. Verifique as páginas de referência da API T2V e I2V para a lista atual de parâmetros, incluindo qualquer campo with_audio.

Quanto tempo leva uma tarefa de geração 4K?

A geração 4K leva mais tempo que 1080P. Espere pelo menos 60–180 segundos para um clipe de 5 segundos, dependendo da carga da fila. Projete sua lógica de consulta com um tempo limite de pelo menos 10 minutos e trate TASK_STATUS_PROCESSING como um estado intermediário normal.

O endpoint I2V é útil para filmagens de produtos ou marcas?

Sim, quando a imagem de entrada é limpa e bem iluminada. O endpoint I2V preserva bem a composição do primeiro quadro para assuntos estacionários. Para movimento complexo de câmera ou cenas com vários personagens, execute um pequeno lote de teste antes de uma produção completa.

Artigos recomendados

• Kling 3.0 Agora na Novita AI: Geração de Vídeo AI Cinematográfica em Escala
• Kling O1 na Novita AI: Modos T2V, I2V, Ref2V e Edição de Vídeo
• API Kling V2.5 Turbo na Novita AI: Texto-para-Vídeo e Imagem-para-Vídeo