Como usar a API do Kling 3.0? Tutorial em chinês de texto para vídeo e imagem para vídeo

TL;DR

• O Kling 3.0 (可灵 3.0) é um modelo de vídeo da Kuaishou; na HiAPI há duas entradas: texto para vídeo kling-3.0/text-to-video e imagem para vídeo kling-3.0/image-to-video, com clipes de 3 a 15 segundos, até 4K e áudio nativo.Abra a página do modelo para gerar online; novos usuários ganham 200 créditos ao se registrar.
• Cobrança por segundo: 720p $0.10 por segundo, com áudio $0.143; 1080p $0.129, com áudio $0.193; 4K $0.479. 5 segundos em 720p custam apenas $0.50.
• A API em dois passos: POST /v1/tasks para enviar e obter o taskId para consultar o resultado. Os exemplos em curl e Python abaixo podem ser copiados e executados.

Veja o resultado primeiro

Texto para vídeo: um prompt em inglês, uma requisição.

A lone red fox sprints across a windswept snowy ridge at golden hour, powder snow kicking up behind each stride, then leaps over a frozen creek in a graceful arc. Cinematic, dramatic side lighting, ultra-detailed fur, shallow depth of field, smooth motion.

Gerar com este prompt → (5 segundos, 16:9)

Exemplo da página do modelo kling-3.0/text-to-video, 5 segundos. Em 720p sem áudio custa $0.50; em 1080p com áudio, $0.965.

Imagem para vídeo: use a imagem do farol abaixo como primeiro quadro.

The waves surge and crash against the rocks, the lighthouse beam sweeps slowly across the stormy night sky, rain streaks through the wind. Smooth cinematic motion, synchronized ambient sound of waves and storm.

Gerar com este prompt → (envie sua imagem inicial, 5 segundos)

Exemplo da página do modelo kling-3.0/image-to-video, 5 segundos. Em 720p com áudio custa $0.715.

Como escolher entre Kling 3.0, Omni e Turbo?

Na HiAPI, o Kling 3.0 tem três linhas, com nomes de modelo, preços e parâmetros diferentes:

Modelo	Entradas	720p / segundo	1080p / segundo	4K / segundo	Indicado para
Kling 3.0 kling-3.0/*	Texto para vídeo, imagem para vídeo (primeiro quadro ou primeiros e últimos quadros)	$0.10, com áudio $0.143	$0.129, com áudio $0.193	$0.479	Vídeo final com áudio, curtas com vários planos
Kling 3.0 Omni kling-3.0-omni/*	Texto para vídeo, imagem para vídeo, referência para vídeo, reescrita de vídeo	$0.10, com áudio $0.129	$0.129, com áudio $0.1645	$0.479	Fixar personagens/produtos, seguir o movimento de um vídeo de referência
Kling 3.0 Turbo kling-3.0-turbo/*	Texto para vídeo, imagem para vídeo	$0.13	$0.16	—	Sem distinção de áudio, cobrança apenas por resolução

Se você só precisa de texto para vídeo e imagem para vídeo, escolha kling-3.0; para fixar o sujeito com imagem de referência, usar vídeo de referência ou reescrever um vídeo existente, veja o tutorial em chinês do Kling 3.0 Omni.

Dois caminhos para começar

Teste online (sem código)

1. Abra a página do modelo Kling 3.0 texto para vídeo e registre-se ou faça login.
2. Cole o prompt, escolha duração, resolução, proporção e decida se quer áudio.
3. Clique em gerar e baixe o vídeo quando estiver pronto.

Chamada da API

1. Crie uma API Key no console.
2. Envie a tarefa com POST https://api.hiapi.ai/v1/tasks; a resposta traz o taskId.
3. Consulte o status com GET /v1/tasks/{taskId}; quando status for success, baixe o vídeo em output[0].url.

curl: o primeiro vídeo

5 segundos em 720p sem áudio, $0.50:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/text-to-video",
    "input": {
      "prompt": "金色夕阳下，一只红狐在风雪覆盖的山脊上疾奔，雪粉飞扬，电影级侧光，平滑跟拍",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "sound": false
    }
  }'

Resposta:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Consultar o resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: enviar, consultar e baixar

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(model, timeout_s=900, **params):
    body = {"model": model, "input": params}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# 竖屏、带声音的口播短视频
url = generate(
    "kling-3.0/text-to-video",
    prompt="竖屏短视频：一位博主拿着新耳机对着镜头介绍，手势自然，室内自然光，口型和说话声同步",
    duration=6, resolution="1080p", aspect_ratio="9:16", sound=True,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Este clipe de 6 segundos em 1080p com áudio custa $1.158.

Imagem para vídeo: um primeiro quadro ou dois quadros (inicial e final)

Troque o nome do modelo para kling-3.0/image-to-video e coloque as imagens em image_urls: 1 imagem é o primeiro quadro; 2 imagens são [primeiro quadro, último quadro].

{
  "model": "kling-3.0/image-to-video",
  "input": {
    "image_urls": [
      "https://your-cdn.example.com/start.jpg",
      "https://your-cdn.example.com/end.jpg"
    ],
    "prompt": "镜头缓慢推进，两个画面之间平滑过渡",
    "duration": 5,
    "resolution": "720p",
    "sound": false
  }
}

• As imagens aceitam JPEG / PNG / WebP; SVG não é suportado.
• Imagem para vídeo não tem aspect_ratio; a proporção segue o primeiro quadro.
• O prompt é opcional; descreva "como deve se mover a seguir" em vez de redescrever a imagem inteira.

Visão geral dos parâmetros

Parâmetro	Valores	Descrição
prompt	string	Obrigatório em texto para vídeo; opcional em imagem para vídeo
image_urls	1–2 imagens	Apenas imagem para vídeo; 1 imagem é o primeiro quadro, 2 são primeiro e último quadros
duration	inteiro de 3–15, padrão 5	Em segundos
resolution	720p / 1080p / 4K, padrão 1080p	Se omitido, a cobrança é em 1080p
aspect_ratio	16:9 / 9:16 / 1:1, padrão 16:9	Apenas texto para vídeo
sound	padrão false	Quando ativado, gera diálogos, efeitos sonoros e som ambiente

Calcule o custo

Duração	720p	720p com áudio	1080p	1080p com áudio	4K
3 segundos	$0.30	$0.429	$0.387	$0.579	$1.437
5 segundos	$0.50	$0.715	$0.645	$0.965	$2.395
10 segundos	$1.00	$1.43	$1.29	$1.93	$4.79
15 segundos	$1.50	$2.145	$1.935	$2.895	$7.185

O padrão de resolution é 1080p; ao ajustar prompts, lembre-se de especificar 720p para economizar mais de 20%. Para mais comparações de preço, veja preços da API do Kling 3.0.

Cuidados antes de ir para produção

• Use callback em vez de polling: no nível superior da requisição (mesmo nível de input), adicione "callback": {"url": "https://seu-dominio/hiapi/callback"} e deduplique por taskId.
• Salve imediatamente: output[0].url é um link temporário; assim que recebê-lo, copie para o seu próprio armazenamento.
• Retentativas com chave de idempotência: adicione Idempotency-Key ao cabeçalho; a mesma chave só cria a tarefa uma vez em retentativas.
• Reembolso automático em caso de falha: a cobrança é apenas por vídeos gerados com sucesso.

Perguntas frequentes

Posso escrever o prompt em chinês?

Sim. Chinês e inglês funcionam, e o conteúdo do diálogo também pode ser escrito diretamente no prompt.

O áudio tem custo adicional?

Com sound: true o preço por segundo é maior: 720p sobe de $0.10 para $0.143, e 1080p de $0.129 para $0.193. Se você só quer a imagem, mantenha o padrão false.

Qual é a duração máxima de um clipe?

3–15 segundos. Para vídeos mais longos, gere por partes e edite depois.

Como escolher entre Kling 3.0 e Seedance 2.5?

O Kling 3.0 tem preço unitário mais baixo e suporta 4K; o Seedance 2.5 gera clipes de até 30 segundos. Veja a comparação em diferenças entre Kling 3.0 e Seedance 2.5.

Se quiser formas prontas de escrever prompts, veja o guia de prompts do Kling 3.0; você também pode copiar o prompt da raposa vermelha acima e gerar na página do modelo.