> ## 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. # Enviar vídeo > Envie vídeos MP4, MOV ou WebM e receba uma URL pública para APIs de geração. Limite padrão: 50MB por arquivo. > [!NOTE] > > Envie referências e receba uma URL pública diretamente em caso de sucesso, sem consultas periódicas. O upload é gratuito, mas o saldo da conta deve ser positivo. Os três endpoints compartilham uma cota por usuário: por padrão, 2000 arquivos em 72 horas. > [!NOTE] > > O Playground da documentação não aceita uploads de arquivos. Use os exemplos cURL, Python ou JavaScript. O exemplo JavaScript exige um `` com um arquivo selecionado. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/uploads/videos \ --header 'Authorization: Bearer ' \ --form 'file=@/path/to/reference.mp4' ``` ```python Python theme={null} import requests with open("reference.mp4", "rb") as file: response = requests.post( "https://api.apimart.ai/v1/uploads/videos", headers={"Authorization": "Bearer "}, files={"file": file} ) response.raise_for_status() result = response.json() print(result["url"]) ``` ```javascript JavaScript theme={null} const input = document.querySelector('input[type="file"]'); const file = input?.files?.[0]; if (!file) throw new Error("Select a file first"); const formData = new FormData(); formData.append("file", file, file.name); const response = await fetch("https://api.apimart.ai/v1/uploads/videos", { method: "POST", headers: { Authorization: "Bearer " }, body: formData }); const result = await response.json(); if (!response.ok) { throw new Error(result.error?.message ?? `HTTP ${response.status}`); } console.log(result.url); ``` ```json 200 theme={null} { "url": "https://cdn.example/uploads/reference.mp4", "filename": "reference.mp4", "content_type": "video/mp4", "file_type": "video", "bytes": 235680, "created_at": 1793836800, "quota": { "limit": 2000, "used": 124, "remaining": 1876, "window_hours": 72, "reset_at": 1794063600 } } ``` ```json 402 theme={null} { "error": { "message": "insufficient balance: uploading files requires a positive account balance, please top up", "type": "insufficient_user_quota" } } ``` ```json 413 theme={null} { "error": { "message": "video file exceeds maximum 52428800 bytes (50MB)", "type": "invalid_request_error" } } ``` ```json 429 theme={null} { "error": { "message": "upload limit reached: each account can upload at most 2000 files per 72 hours", "type": "rate_limit_exceeded", "code": "rate_limit_exceeded", "param": "" }, "quota": { "limit": 2000, "used": 2000, "remaining": 0, "window_hours": 72, "reset_at": 1794063600 } } ``` ## Autenticação **Authorization** `string` *required* Use uma APIMart API Key válida, habilitada e não expirada como `Bearer `. A conta não pode estar suspensa e deve ter saldo positivo. Esgotar a cota própria da Key não impede uploads. Obtenha uma Key em [Gerenciamento de API Keys](https://apimart.ai/keys). ## Parâmetros da solicitação **file** `file` *required* Envie um arquivo com seu nome no campo `file` de uma solicitação `multipart/form-data`. Não substitua a parte do arquivo por JSON, string base64 ou URL. Outros campos são ignorados; se houver várias partes `file`, somente a primeira será processada. **Formatos aceitos:** MP4 (.mp4), MOV (.mov), WebM (.webm) **Tamanho máximo padrão:** 50MB. Os limites de tamanho são configuráveis. Valem a configuração atual e o limite indicado na mensagem de erro. Com cURL `--form`, Python `files` ou JavaScript `FormData`, deixe o cliente gerar `Content-Type` com a boundary. Não defina esse cabeçalho manualmente. ## Validação de arquivos O tipo é detectado pelo conteúdo, não pela extensão ou MIME informado. O conteúdo deve corresponder ao endpoint. Renomear não converte o formato; tipos incompatíveis retornam HTTP `400`. A estrutura do contêiner é validada. Cabeçalhos falsos e contêineres corrompidos são rejeitados. Apenas os formatos abaixo são aceitos; renomear AVI, MKV ou outros não os torna compatíveis. | Formato | Tipo MIME detectado | | - | - | | MP4 (.mp4) | `video/mp4` | | MOV (.mov) | `video/quicktime` | | WebM (.webm) | `video/webm` | ## Resposta de sucesso HTTP `200` retorna os dados do arquivo. `url` fica na raiz do JSON, sem objeto `data` envolvendo a resposta nem ID de tarefa de geração. **url** `string` URL pública para o parâmetro de referência apropriado da API de geração. Cada modelo mantém seus limites de formato, tamanho, quantidade e duração. Upload bem-sucedido não garante compatibilidade com o modelo. **filename** `string` Nome original do arquivo. **content\_type** `string` Tipo MIME detectado pelo servidor a partir do conteúdo, não o declarado pelo cliente. **file\_type** `string` Categoria do arquivo. Este endpoint retorna `video`. **bytes** `integer` Tamanho real em bytes. **created\_at** `integer` Horário do upload como timestamp Unix em segundos. **quota** `object` Informações opcionais de cota. Os campos de usuários limitados estão abaixo. A estrutura pode variar para acesso ilimitado ou estatísticas indisponíveis. | Campo | Descrição | | - | - | | `quota.limit` | Máximo de uploads bem-sucedidos deste usuário na janela; pode diferir do padrão de 2000. | | `quota.used` | Quantidade usada na janela, incluindo este upload bem-sucedido. | | `quota.remaining` | Quantidade de arquivos que ainda podem ser enviados no momento. | | `quota.window_hours` | Duração da janela em horas; padrão 72. | | `quota.reset_at` | Momento em que o lote mais antigo sai da janela, em segundos Unix. Algumas vagas são liberadas; a cota inteira não necessariamente reinicia de uma vez. | ## Cota compartilhada e limites de requisições Imagens, vídeos e áudios compartilham uma cota por usuário. Várias Keys do mesmo usuário não somam cota. A janela avança a cada hora cheia e conta, por padrão, os uploads bem-sucedidos das últimas 71–72 horas aproximadamente. Arquivos inválidos, grandes demais ou não armazenados não consomem cota de arquivos. Respostas limitadas comuns incluem `X-Upload-Quota-Limit`, `X-Upload-Quota-Remaining` e `X-Upload-Quota-Reset`, correspondentes a `limit`, `remaining` e `reset_at`. Reset está em segundos Unix. Usuários ilimitados recebem `quota: {"unlimited": true}` sem esses três cabeçalhos. Se as estatísticas estiverem indisponíveis, uma resposta de sucesso pode omitir `quota`. Não interprete a ausência como zero ou ilimitado, nem repita o upload apenas por esse motivo. Cota de arquivos esgotada retorna HTTP `429`, `error.type: rate_limit_exceeded`, `quota` com `remaining: 0` e `Retry-After`. Aguarde os segundos indicados. Há outro limite independente de 1000 requisições por Key a cada 60 segundos, identificado por `rate_limit_error`. ## Tratamento de erros Os erros ficam no objeto `error` na raiz do JSON. Verifique o status HTTP, `error.type` / `error.code` e `error.message`. | HTTP | `error.type` | Causa e ação | | - | - | - | | 400 | `invalid_request_error` | Arquivo ausente, solicitação sem multipart, arquivo vazio, tipo incorreto, formato incompatível ou conteúdo corrompido. Corrija o arquivo ou endpoint. | | 401 / 403 | `—` | Key inválida ou desabilitada, ou conta suspensa. Verifique a autenticação e o status da conta. | | 402 | `insufficient_user_quota` | Saldo não positivo ou Key expirada. Adicione saldo ou use uma Key válida. Uploads gratuitos também exigem essas condições. | | 413 | `invalid_request_error` | Arquivo acima do limite do seu tipo. Comprima ou reduza o tamanho; consulte o limite atual no erro. | | 429 | `rate_limit_exceeded` | Cota compartilhada esgotada. Leia `quota` e `Retry-After` e aguarde vagas disponíveis. | | 429 | `rate_limit_error` | Requisições excessivas da Key. Reduza a frequência e aumente o intervalo entre tentativas. | | 503 | `server_error` | Muitos uploads simultâneos de vídeo/áudio ou armazenamento temporariamente indisponível. Tente novamente mais tarde. | | 500 | `server_error` | Falha ao gravar o arquivo. Tente novamente mais tarde. | ## Uso das URLs e conservação 72 horas é a janela padrão da cota, não uma garantia de conservação dos arquivos. A duração depende da política de armazenamento. Preserve os originais e use as URLs prontamente na geração; não suponha que sejam permanentes. ## Outros endpoints de upload * [Enviar imagem](https://docs.apimart.ai/pt/api-reference/uploads/images.md) * [Enviar áudio](https://docs.apimart.ai/pt/api-reference/uploads/audios.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.