> ## 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. # Geração de vídeos Muse Video Ext > Gere um vídeo MP4 a partir de texto ou de até 9 imagens de referência: cerca de 10 segundos, 720p, com som. > [!NOTE] > > Esta API é assíncrona. Salve o ID da tarefa após o envio e consulte `GET /v1/tasks/{task_id}` para obter status e resultados. Na resposta padrão de envio, o ID está em `data[0].task_id`. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/videos/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Idempotency-Key: ' \ --data '{ "model": "muse-video-ext", "prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text", "aspect_ratio": "16:9", "duration": 10, "resolution": "720p" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/videos/generations", headers={ "Authorization": "Bearer ", "Accept": "application/json", "Idempotency-Key": "" }, json={ "model": "muse-video-ext", "prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text", "aspect_ratio": "16:9", "duration": 10, "resolution": "720p" } ) 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", Accept: "application/json", "Idempotency-Key": "" }, body: JSON.stringify({ "model": "muse-video-ext", "prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text", "aspect_ratio": "16:9", "duration": 10, "resolution": "720p" }) }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## Cabeçalhos da solicitação **Authorization** `string` *required* Use uma APIMart API Key no formato `Bearer `. O envio e as consultas exigem autenticação com a mesma identidade de usuário. **Idempotency-Key** `string` Fortemente recomendado. Use uma nova chave para cada geração independente (1–191 caracteres ASCII visíveis; UUID recomendado). Substitua `` nos exemplos. Após um timeout de envio ou falha de rede, repita com o mesmo endpoint, corpo, versão de resposta e chave. Depois de receber o ID, consulte apenas essa tarefa. ## Parâmetros da solicitação **model** `string` *required* Valor fixo: `muse-video-ext`. **prompt** `string` *required* Descrição do conteúdo desejado, em chinês ou inglês. Não pode ficar vazia após remover espaços nas extremidades. Obrigatória mesmo com imagens de referência. **image\_urls** `string[]` Até 9 entradas de imagens de referência não vazias. Aceita URLs públicas, Data URIs (como `data:image/png;base64,...`) ou base64 puro. Omita ou envie `[]` para gerar apenas a partir de texto. PNG, JPEG e WebP são recomendados. As URLs devem ser acessíveis diretamente pelo servidor, sem cookies de login do navegador. O tamanho original combinado de todas as imagens não pode exceder **11 MiB (11.534.336 bytes)**. É um limite total, não por imagem. A codificação base64 aumenta o corpo da solicitação. Não envie URLs `blob:`, caminhos locais ou objetos `File`. **aspect\_ratio** `string` Aceita as sete proporções abaixo. Quando omitido, texto para vídeo usa `16:9`; com referências, segue a composição delas. Uma proporção explícita tem prioridade. Para seleção automática, omita o campo; não envie `"auto"`. `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` **size** `string` Campo de compatibilidade que aceita as sete proporções acima ou `auto`, mas não dimensões em pixels como `1024x1024`. Enviar apenas `size: "auto"` equivale a não definir uma proporção. Prefira `aspect_ratio`. Se ambos forem válidos, `aspect_ratio` tem prioridade, mas os campos são validados separadamente: uma proporção válida não corrige um `size` inválido. **n** `integer` (default: 1) Um único resultado por solicitação. Só aceita o número `1`. Valores explícitos como `0`, negativos ou maiores que `1` causam erro. **duration** `integer | string` (default: 10) Fixa em cerca de 10 segundos. Aceita o número `10` ou as strings `"10"` e `"10s"`; recomenda-se o número `10`. Aliases compatíveis: `seconds` e `duration_seconds`. Use apenas um campo de duração; cada campo enviado é validado separadamente. **resolution** `string` (default: 720p) Apenas `720p` é aceito, não `1080p` ou `4k`. As dimensões e a duração reais devem ser obtidas dos metadados da mídia retornada. **audio** `boolean` Os vídeos incluem som por padrão; o campo pode ser omitido. `true` não altera esse comportamento e `false` é rejeitado. > [!NOTE] > > Retorna uma URL MP4: cerca de 10 segundos, 720p, com som. As imagens de referência orientam a geração, sem garantia de um primeiro quadro idêntico pixel a pixel. ### Outros parâmetros opcionais **webhook** `string` URL base do backend para notificações da tarefa. A plataforma remove as barras finais e acrescenta `/callback`: `https://your-backend.example/muse` torna-se `https://your-backend.example/muse/callback`. Omita se usar apenas consultas periódicas. **language** `string` Controla o idioma dos erros do Webhook, não o conteúdo gerado. Valores: `zh`, `en`, `ja`, `ko`, `ru`, `fr`, `de`, `id`, `pt`, `es`. Tags regionais como `zh-CN` não são aceitas. Nas consultas, envie o idioma separadamente como parâmetro GET. ## Geração com imagens de referência ```json theme={null} { "model": "muse-video-ext", "prompt": "The fox in the reference image slowly raises its head, wind moves its fur, gentle camera push-in", "image_urls": [ "https://your-cdn.example/fox.png" ], "duration": 10, "resolution": "720p" } ``` Substitua a URL de exemplo por uma URL de imagem acessível. O exemplo omite a proporção para seguir a composição da referência; adicione `aspect_ratio` para uma proporção fixa. Adicione outras referências em `image_urls`, até 9 no total. ## Resposta de envio A resposta padrão é HTTP `200`, com `data` como array. `submitted` significa que a tarefa foi aceita, não concluída. Salve `data[0].task_id` e depois consulte a tarefa. > **Versão de resposta opcional: 2026-07-27** > > Com o cabeçalho `X-APIMart-Response-Version: 2026-07-27`, o envio retorna HTTP `202`. Leia o ID em `data.id` e o caminho de consulta em `data.poll_url`. > > ```json theme={null} > { > "code": 202, > "request_id": "req_example", > "data": { > "id": "task_01K...", > "object": "generation.task", > "type": "video", > "status": "pending", > "progress": 0, > "poll_url": "/v1/tasks/task_01K..." > } > } > ``` > > Esta versão não altera a estrutura da resposta GET. Ao adicionar esse cabeçalho, não continue lendo o ID da resposta de envio em `data[0].task_id`. ## Consultar status e resultados Use o ID completo recebido no envio e a mesma identidade de usuário. `language` é opcional e define o idioma dos erros. Consulte todos os campos em [Status da tarefa](https://docs.apimart.ai/pt/api-reference/tasks/status.md). ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/?language=pt' \ --header 'Authorization: Bearer ' ``` Consulte a cada 5–10 segundos, sem consultas simultâneas para a mesma tarefa. Um timeout do cliente ou a interrupção das consultas não cancela a tarefa no servidor. Guarde o ID e retome as consultas GET depois; não envie automaticamente uma nova geração. | `data.status` | Ação | | - | - | | `pending` / `processing` | Na fila ou em processamento; continue consultando. | | `completed` | Geração concluída com sucesso; pare as consultas e leia a URL do resultado. | | `failed` | Falha na geração; pare as consultas e leia `data.error.message`. | | `unknown` / … | Status incerto. Guarde o ID e limite as novas consultas; não trate como sucesso nem gere novamente de forma automática. | Determine o término por `data.status`. HTTP `200` ou `progress: 100` não indica, por si só, sucesso na geração. Um `polling_error` durante o processamento não é uma falha terminal. Exemplo de resposta de consulta concluída (URL do resultado ilustrativa): ```json theme={null} { "code": 200, "data": { "id": "task_01K...", "status": "completed", "progress": 100, "result": { "videos": [ { "url": [ "https://cdn.example/generated-video.mp4" ] } ] } } } ``` Nas respostas de consulta, `data` é um objeto e `url` é um array de strings. O primeiro resultado está em `data.result.videos[0].url[0]`. Se presente, `expires_at` é o vencimento em segundos Unix; salve os arquivos necessários antes disso. `actual_time` mede o tempo de processamento da tarefa, não a duração de reprodução do vídeo. ## Limitações e tratamento de erros Vídeos e áudios de referência, máscaras, controle do primeiro/último quadro, extensão e remix não são compatíveis. `quality` não tem efeito. Omita `seed`, `negative_prompt`, `width`, `height`, `response_format` e `output_format`, pois não são parâmetros de geração deste modelo. `async: false` não ativa geração síncrona e `stream` não oferece um fluxo SSE de geração. | HTTP / `error.code` | Ação | | - | - | | `400 / invalid_request_error` | Verifique o prompt, a quantidade de referências, a proporção, a quantidade de resultados e as especificações fixas. | | `409 / idempotency_in_progress` | Aguarde conforme `Retry-After` e repita a solicitação original com a mesma chave de idempotência. | | `409 / idempotency_key_reused` | A mesma chave foi usada em solicitações diferentes. Corrija o uso das chaves; cada geração independente exige uma nova chave. | | `409 / idempotency_result_indeterminate` | Pare os reenvios automáticos e preserve a chave e os dados da tarefa para investigação. | | `429` | Aguarde conforme `Retry-After` antes de tentar novamente. | Tarefas com falha também podem retornar HTTP `200`; examine `data.status` e `data.error.message`. Um erro de rede ou `5xx` durante o envio pode ocorrer após a aceitação, portanto não reenvie imediatamente com uma nova chave. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.