Kling Imagem para vídeo
Use o endpoint de imagem para vídeo para criar uma Task assíncrona.
Visão geral
Use o endpoint de imagem para vídeo com um modelo compatível. Use o Task ID retornado para recuperar seu estado, ou forneça callback_url para as entregas documentadas abaixo.
Início rápido
- Crie uma Chave de API e defina-a como RUNAPI_API_KEY.
- Escolha um modelo compatível e envie uma requisição POST cujo corpo corresponda ao schema desse modelo.
- Armazene o ID da tarefa retornado e, em seguida, faça polling até atingir um estado terminal ou trate os callbacks documentados abaixo.
Endpoint
- URL base
https://runapi.ai- Versão da API
v1- Autenticação
Authorization: Bearer YOUR_API_TOKEN
Modelos suportados
Abra uma página de modelo para ver preços atuais, limites de taxa e detalhes de uso comercial.
Esquema de solicitação
Os campos e valores permitidos dependem do modelo selecionado. Quando fornecido, callback_url recebe as entregas da Task documentadas abaixo.
kling-o113 campos
aspect_ratiostringProporção de aspecto da saída.
Valores permitidos:16:9, 9:16, 1:1
Padrão: 16:9
callback_urlstringURL de webhook para notificações assíncronas.
duration_secondsintegerDuração em segundos.
Valores permitidos:5
Padrão: 5
enable_soundbooleanA geração de som deve permanecer desativada.
Padrão:false
first_frame_image_urlstringURL de imagem HTTP(S) pública JPG, JPEG ou PNG do primeiro quadro.
last_frame_image_urlstringURL de imagem HTTP(S) pública JPG, JPEG ou PNG do quadro final; não pode ser combinada com reference_image_urls ou reference_video_url.
modestringModo de geração.
Valores permitidos:std, pro
Padrão: std
modelstringSlug do modelo.
preserve_reference_video_audiobooleanPreservar o áudio original do vídeo de referência.
Padrão:false
promptstringDescrição do vídeo; referencie mídias com marcadores numerados correspondentes.
Intervalo:1 - 2500
reference_image_urlsarrayURLs de imagens de referência JPG, JPEG ou PNG via HTTP(S) público, ordenadas; não pode ser combinado com last_frame_image_url.
Intervalo de itens:1 - 7
reference_video_typestringUse o vídeo como base de edição ou referência de recurso.
Valores permitidos:base, feature
Padrão: base
reference_video_urlstringURL de vídeo de referência HTTP(S) pública MP4 ou MOV; não pode ser combinada com last_frame_image_url.
kling-v2.1-master-image-to-video9 campos
aspect_ratiostringProporção de aspecto da saída.
callback_urlstringURL de webhook para notificações assíncronas.
cfg_scalenumberEscala de orientação (0-1).
duration_secondsintegerDuração em segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL da imagem do primeiro quadro.
last_frame_image_urlstringURL da imagem do quadro final para modelos de imagem-para-vídeo compatíveis.
modelstringSlug do modelo.
negative_promptstringPrompt negativo.
promptstringDescrição do vídeo.
kling-v2.1-pro9 campos
aspect_ratiostringProporção de aspecto da saída.
callback_urlstringURL de webhook para notificações assíncronas.
cfg_scalenumberEscala de orientação (0-1).
duration_secondsintegerDuração em segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL da imagem do primeiro quadro.
last_frame_image_urlstringURL da imagem do quadro final para modelos de imagem-para-vídeo compatíveis.
modelstringSlug do modelo.
negative_promptstringPrompt negativo.
promptstringDescrição do vídeo.
kling-v2.1-standard9 campos
aspect_ratiostringProporção de aspecto da saída.
callback_urlstringURL de webhook para notificações assíncronas.
cfg_scalenumberEscala de orientação (0-1).
duration_secondsintegerDuração em segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL da imagem do primeiro quadro.
last_frame_image_urlstringURL da imagem do quadro final para modelos de imagem-para-vídeo compatíveis.
modelstringSlug do modelo.
negative_promptstringPrompt negativo.
promptstringDescrição do vídeo.
kling-v2.5-turbo-image-to-video-pro9 campos
aspect_ratiostringProporção de aspecto da saída.
callback_urlstringURL de webhook para notificações assíncronas.
cfg_scalenumberEscala de orientação (0-1).
duration_secondsintegerDuração em segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL da imagem do primeiro quadro.
last_frame_image_urlstringURL da imagem do quadro final para modelos de imagem-para-vídeo compatíveis.
modelstringSlug do modelo.
negative_promptstringPrompt negativo.
promptstringDescrição do vídeo.
kling-v2.69 campos
aspect_ratiostringProporção de aspecto da saída.
Valores permitidos:16:9, 9:16, 1:1
Padrão: 16:9
callback_urlstringURL de webhook para notificações assíncronas.
duration_secondsintegerDuração em segundos.
Valores permitidos:5, 10
Padrão: 5
enable_soundbooleanAtivar geração de som; requer modo pro.
Padrão:false
first_frame_image_urlstringURL da imagem do primeiro quadro.
last_frame_image_urlstringURL da imagem do quadro final; requer modo pro e 5 segundos.
modestringModo de geração.
Valores permitidos:std, pro
Padrão: std
modelstringSlug do modelo.
promptstringDescrição do vídeo.
Intervalo:1 - 2500
kling-v3-omni9 campos
aspect_ratiostringProporção de aspecto da saída.
Valores permitidos:16:9, 9:16, 1:1
Padrão: 16:9
callback_urlstringURL de webhook para notificações assíncronas.
duration_secondsintegerDuração em segundos.
Valores permitidos:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Padrão: 5
enable_soundbooleanAtivar geração de som sincronizado.
Padrão:false
first_frame_image_urlstringURL da imagem do primeiro quadro.
last_frame_image_urlstringURL da imagem do quadro final; requer duração de 5 segundos.
modelstringSlug do modelo.
output_resolutionstringResolução de saída.
Valores permitidos:720p, 1080p, 4k
Padrão: 720p
promptstringDescrição do vídeo.
Intervalo:1 - 2500
kling-v3-turbo-image-to-video6 campos
callback_urlstringURL de webhook para notificações assíncronas.
duration_secondsintegerDuração em segundos.
Valores permitidos:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Padrão: 5
first_frame_image_urlstringURL da imagem do primeiro quadro.
modelstringSlug do modelo.
output_resolutionstringResolução de saída.
Valores permitidos:720p, 1080p
Padrão: 720p
promptstringDescrição do vídeo.
Intervalo:1 - 2500
Regras condicionais
Esses requisitos se aplicam quando todas as condições listadas corresponderem.
-
Quando
model = kling-o1- Obrigatório
- Não aceito
output_resolution,negative_prompt,cfg_scale
-
Quando
model = kling-v2.1-master-image-to-video- Obrigatório
- Não aceito
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Quando
model = kling-v2.1-pro- Obrigatório
- Não aceito
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Quando
model = kling-v2.1-standard- Obrigatório
- Não aceito
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Quando
model = kling-v2.5-turbo-image-to-video-pro- Obrigatório
- Não aceito
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Quando
model = kling-v2.6- Obrigatório
- Não aceito
output_resolution,negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Quando
model = kling-v3-omni- Obrigatório
- Não aceito
negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Quando
model = kling-v3-turbo-image-to-video- Obrigatório
- Não aceito
enable_sound,aspect_ratio,negative_prompt,cfg_scale,last_frame_image_url,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
Criar aceitação
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta em processamento
GET /api/v1/kling/image_to_video/:id
Esquema de resposta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta concluída
GET /api/v1/kling/image_to_video/:id
Esquema de resposta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}
Consulta falhou
GET /api/v1/kling/image_to_video/:id
Esquema de resposta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}
Callback do cliente: concluído
POST callback_url
Esquema de resposta
{
"properties": {
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}
Callback do cliente: falhou
POST callback_url
Esquema de resposta
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Authentication required"
}
Erros
GET /api/v1/kling/image_to_video/:id
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Authentication required"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"oneOf": [
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Resumo de validação legível por humanos.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Mensagens de validação com chaves por campo de requisição público, com um array de strings legíveis por humanos para cada campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}
Exemplo de resposta
{
"error": "model must be one of: kling-o1, kling-v2.1-master-image-to-video, kling-v2.1-pro, kling-v2.1-standard, kling-v2.5-turbo-image-to-video-pro, kling-v2.6, kling-v3-omni, kling-v3-turbo-image-to-video"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Insufficient balance"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "API key credit limit exceeded"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "The request uses features that are not supported for the selected model"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Rate limit reached. Please retry later."
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Service under maintenance, please try again later"
}
Erros
POST /api/v1/kling/image_to_video
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "The request timed out"
}
Erros
GET /api/v1/kling/image_to_video/:id
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Task with id 'tsk_reference_demo' not found"
}
Exemplos de Código Gerados
Use cURL diretamente ou instale um SDK para a sua linguagem. Cada exemplo submete a requisição validada mostrada nesta referência.
Instalar
pip install runapi-kling
import os
from runapi.kling import KlingClient
client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.image_to_video.create(
model="kling-o1",
prompt="A gentle camera pan across the scene.",
first_frame_image_url="https://file.runapi.ai/first-frame.png"
)