> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling V4 Geração de vídeos > Texto para vídeo, imagem para vídeo, geração com referências, edição e extensão de vídeo. Gere 3–30 segundos em 720p / 1080p, sempre com áudio estéreo. > [!NOTE] > > Este endpoint é assíncrono. Após o envio, use o `task_id` retornado com `GET /v1/videos/generations/{task_id}` para consultar o status e o resultado. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/videos/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "kling-v4", "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain", "duration": 5, "resolution": "720p", "aspect_ratio": "9:16" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/videos/generations", headers={"Authorization": "Bearer "}, json={ "model": "kling-v4", "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain", "duration": 5, "resolution": "720p", "aspect_ratio": "9:16" } ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.apimart.ai/v1/videos/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify({ model: "kling-v4", prompt: "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain", duration: 5, resolution: "720p", aspect_ratio: "9:16" }) }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ## Seleção do modo Os cinco modos usam o mesmo modelo, `kling-v4`. O modo é selecionado conforme os arquivos enviados e `omni_reference_task_type`. | Modo | Entrada | | - | - | | Texto para vídeo | Sem arquivos de imagem, vídeo ou áudio | | Imagem para vídeo | Um quadro inicial; opcionalmente, um quadro final e até 8 intermediários | | Geração com referências | Envie `video_urls`, `audio_urls` ou `reference_image` em `image_with_roles`; ou defina explicitamente `omni_reference_task_type: "reference"` | | Edição de vídeo | Defina `omni_reference_task_type: "edit"` e forneça um vídeo de entrada | | Extensão de vídeo | Defina `omni_reference_task_type: "extend"` e forneça um vídeo de entrada | `omni_reference_task_type` usa `auto` por padrão, equivalente a omitir o campo. Com `reference` explícito, as imagens de `image_urls` são tratadas como referências. > [!WARNING] > > Enviar apenas `video_url` sem especificar `edit` ou `extend` retorna HTTP 400. Para usar um vídeo como referência, use `video_urls`. ## Cabeçalhos da requisição **Authorization** `string` *required* Autenticação Bearer: `Bearer `, em que `` é sua chave de API APIMart. ## Parâmetros da requisição **model** `string` *required* Deve ser `kling-v4`. **prompt** `string` Descreva o conteúdo a gerar ou editar. Opcional para imagem para vídeo; obrigatório nos demais modos. Na geração com referências, use `@Image1`, `@Video1` e `@Audio1` para indicar os arquivos, numerados a partir de 1 na ordem de cada lista. Na edição, o vídeo de entrada é `@Video1` e as imagens de referência são `@Image1`, `@Image2` etc. **duration** `integer` Duração gerada em segundos, de `3` a `30`; padrão: `5`. * Edição de vídeo: quando omitido, a duração de saída segue a do vídeo de entrada. * Extensão de vídeo: duração do novo trecho. O vídeo retornado combina o original e o novo trecho. **resolution** `string` (default: 720p) Resolução de saída: `720p` ou `1080p`. Use este campo para escolher a resolução; V4 não aceita `mode`. **aspect\_ratio** `string` Aceita `16:9`, `9:16`, `1:1` e `21:9`. A geração com referências também aceita `auto`. | Modo | Comportamento padrão | | - | - | | Texto para vídeo | `16:9` | | Imagem para vídeo | Segue o quadro inicial | | Geração com referências | `auto` | | Edição de vídeo | Segue o vídeo de entrada | | Extensão de vídeo | Este campo não é aceito; a proporção original é preservada | **image\_urls** `string[]` Lista de URLs de imagens, interpretada conforme o modo: * Imagem para vídeo: a primeira imagem é o quadro inicial e a segunda é o final; no máximo 2 imagens. * Geração com referências e edição de vídeo: até 10 imagens de referência. Para gerar usando apenas imagens de referência, defina explicitamente `omni_reference_task_type: "reference"`. As URLs dos arquivos devem ser acessíveis publicamente. **image\_with\_roles** `object[]` Lista de imagens com funções. Cada item contém `url` e `role`. | `role` | Uso | | - | - | | `first_frame` | Quadro inicial para imagem para vídeo; exatamente 1 obrigatório | | `last_frame` | Quadro final para imagem para vídeo, ou quadro final desejado para extensão | | `keyframe` | Quadro intermediário para imagem para vídeo; também aceita `middle_frame`. Usado na ordem da lista, até 8 imagens | | `reference_image` | Imagem de referência para geração com referências | Em imagem para vídeo, os quadros inicial, final e intermediários devem somar no máximo 10 imagens. **first\_frame\_image** `string` URL do quadro inicial para imagem para vídeo. Também pode ser fornecida como `first_frame` em `image_with_roles` ou como primeira imagem de `image_urls`. **last\_frame\_image** `string` URL do quadro final para imagem para vídeo, ou do quadro final desejado para extensão. **video\_urls** `string[]` Vídeos de referência: até 5 clipes, usando no máximo 30 segundos no total. Para edição ou extensão, também é possível enviar exatamente 1 URL de vídeo no lugar de `video_url`, com `omni_reference_task_type: "edit"` ou `"extend"`. **video\_url** `string` URL do vídeo de entrada para edição ou extensão. Exige `omni_reference_task_type: "edit"` ou `"extend"`. Na edição, o vídeo de entrada deve ter pelo menos 3 segundos; durações menores retornam HTTP 400. Se ultrapassar 30 segundos, serão usados os primeiros 30. **audio\_urls** `string[]` Áudios de referência: até 3 clipes, cada um com 5–30 segundos. Na geração com referências, imagens, vídeos e áudios devem somar no máximo 15 arquivos. **omni\_reference\_task\_type** `string` (default: auto) Aceita `auto`, `reference`, `edit` e `extend`. * `auto`: seleciona texto para vídeo, imagem para vídeo ou geração com referências conforme os arquivos; equivale a omitir o campo. * `reference`: geração com referências; imagens de `image_urls` são tratadas como referências. * `edit`: edição de vídeo; exige um vídeo de entrada. * `extend`: extensão de vídeo; exige um vídeo de entrada. **audio\_setting** `string` Aceita `origin` (preservar o áudio do vídeo de entrada) e `auto` (gerar novo áudio). Apenas para edição ou geração com referências que inclua vídeos. * Edição de vídeo: preserva o áudio original por padrão; `auto` gera novo áudio. * Geração com referências que inclua vídeos: gera novo áudio por padrão; `origin` preserva o áudio do vídeo de referência. * Extensão de vídeo: este campo não é aceito. O áudio original é preservado e o novo trecho recebe áudio gerado automaticamente. V4 sempre produz vídeos com áudio estéreo, gerando som e imagem em conjunto. ## Exemplos de requisições As URLs abaixo são ilustrativas. Substitua-as por URLs reais e acessíveis publicamente. ### Imagem para vídeo: quadros inicial e final ```json theme={null} { "model": "kling-v4", "prompt": "The camera slowly moves closer", "image_urls": ["https://example.com/start.png", "https://example.com/end.png"] } ``` A primeira imagem é o quadro inicial e a segunda é o final. `prompt` é opcional para imagem para vídeo. ### Imagem para vídeo: quadros inicial, intermediários e final ```json theme={null} { "model": "kling-v4", "prompt": "A girl walks from the window to the door, then looks back and smiles", "image_with_roles": [ {"url": "https://example.com/1.png", "role": "first_frame"}, {"url": "https://example.com/2.png", "role": "keyframe"}, {"url": "https://example.com/3.png", "role": "keyframe"}, {"url": "https://example.com/4.png", "role": "last_frame"} ], "duration": 10 } ``` Os quadros intermediários são usados na ordem da lista. É necessário exatamente 1 quadro inicial, com no máximo 10 imagens entre quadros inicial, final e intermediários. ### Geração com referências ```json theme={null} { "model": "kling-v4", "prompt": "The girl in @Image1 runs along the beach with the camera movement from @Video1 and background music from @Audio1", "image_with_roles": [ {"url": "https://example.com/girl.png", "role": "reference_image"} ], "video_urls": ["https://example.com/camera.mp4"], "audio_urls": ["https://example.com/bgm.mp3"], "aspect_ratio": "auto", "duration": 5 } ``` Até 10 imagens, 5 vídeos e 3 clipes de áudio de referência, com no máximo 15 arquivos no total. Os vídeos usam até 30 segundos no total; cada áudio deve ter 5–30 segundos. ### Edição de vídeo ```json theme={null} { "model": "kling-v4", "prompt": "Change the scene to a snowy winter night", "omni_reference_task_type": "edit", "video_url": "https://example.com/in.mp4", "image_urls": ["https://example.com/style.png"] } ``` O vídeo de entrada deve ter pelo menos 3 segundos; se ultrapassar 30, serão usados os primeiros 30. Sem `duration` e `aspect_ratio`, a duração e a proporção seguem o vídeo de entrada. O áudio original é preservado por padrão; use `audio_setting: "auto"` para gerar novo áudio. ### Extensão de vídeo ```json theme={null} { "model": "kling-v4", "prompt": "The camera continues moving forward as the sky grows darker", "omni_reference_task_type": "extend", "video_url": "https://example.com/in.mp4", "duration": 5 } ``` A extensão começa no último quadro do vídeo de entrada. O resultado combina o vídeo original e o novo trecho; apenas a duração do novo trecho é cobrada. Forneça um quadro final desejado com `last_frame_image` ou `last_frame` em `image_with_roles`. A extensão não aceita `aspect_ratio` nem `audio_setting`. ## Consultar uma tarefa Substitua o ID da tarefa na requisição abaixo pelo ID retornado no envio: ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/videos/generations/' \ --header 'Authorization: Bearer ' ``` Tempo aproximado de geração: 3 minutos para um vídeo de 3 segundos em 720p e 3,5 minutos para um vídeo de 15 segundos. ## Cobrança Cobrança por segundo. Consulte os [preços dos modelos](https://apimart.ai/pricing). `720p` e `1080p` têm preços distintos. A edição e a geração com referências que inclua vídeos usam a tarifa com vídeo de entrada. Os demais modos usam a tarifa de geração padrão. | Modo | Segundos cobrados | | - | - | | Texto para vídeo, imagem para vídeo, geração com referências apenas de imagens ou áudio | Segundos de saída | | Extensão de vídeo | Segundos do novo trecho | | Edição de vídeo, geração com referências que inclua vídeos | Segundos de saída + max(segundos de saída, segundos de vídeo de entrada) | Os segundos de vídeo de entrada são calculados somando as durações, arredondando para cima e limitando a 30 segundos. Por exemplo, editar um vídeo de 3,04 segundos sem `duration` produz 4 segundos, cobrados como 4 + 4 = 8 segundos. Na edição e na geração com referências que inclua vídeos, a duração do vídeo de entrada é verificada no envio. Se a verificação falhar, retorna HTTP 400 sem cobrança. Gerações com falha recebem reembolso integral. ## Parâmetros não aceitos Os seguintes parâmetros ou valores retornam HTTP 400: * `mode`: V4 não tem níveis `std`, `pro` ou `4k`. Use `resolution`. * `negative_prompt`, `watermark: true`, `audio: false`. * `multi_shot`, `multi_prompt`, `element_list`, `video_list`. * `camera_control`, `voice_list`. ## Erros comuns | Erro | Solução | | - | - | | `video_url needs omni_reference_task_type edit ... or extend` | Especifique `edit` ou `extend` com `video_url`; use `video_urls` para vídeos de referência | | `image-to-video requires exactly 1 first frame` | Forneça exatamente 1 quadro inicial; apenas quadros finais ou intermediários não bastam | | `first frame, last frame and keyframes together are at most 10 images` | Reduza o total de quadros inicial, final e intermediários para no máximo 10 | | `reference images, videos and audios together are at most 15 files` | Reduza o total de arquivos de referência para no máximo 15 | | `video edit requires an input video of at least 3 seconds` | Use um vídeo de entrada com pelo menos 3 segundos | | `Failed to probe the input video duration` | Verifique se a URL está acessível e aponta para um arquivo de vídeo válido | | `has no std/pro/4k mode` | Remova `mode` e use `resolution` | | `Could not download the input from ... (HTTP 403)` | Use uma URL pública sem proteção contra hotlink | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.