---
title: "Criar uma sessão de upload"
description: "Prepare uma URL temporária de upload e cabeçalhos exclusivos para enviar um documento local, incluindo os requisitos para um agente MCP."
canonical: "https://ai-glot.com/docs/pt/api/uploads/create"
updated: "2026-10-02"
---

# Criar uma sessão de upload

Requer `batches:create`. Criar uma sessão não custa créditos nem cria uma tradução. Envie apenas o nome do arquivo, com uma extensão compatível, e o tamanho exato dos bytes originais:

```json
{ "filename": "catalogue.xlsx", "size_bytes": 4096 }
```

A resposta contém `upload_id`, `upload_url`, `method`, `headers`, `expires_at`, `consume_until` e `instructions` em linguagem simples. Use exatamente a URL e os cabeçalhos retornados com um cliente HTTP externo e, em seguida, [crie a tradução](/docs/api/translations/create) com `upload_id`, usando a mesma credencial. O nome do arquivo já está associado à sessão.

```javascript
const session = createUploadResponse.data;
const uploaded = await fetch(session.upload_url, {
  method: session.method,
  headers: session.headers,
  body: originalFileBytes,
  redirect: "error",
});
if (!uploaded.ok) throw new Error(`Upload failed: ${uploaded.status}`);
// Use a credencial original do workspace para POST /v1/batches:
// { upload_id: session.upload_id, instruction: "Translate into French" }
```

O cabeçalho temporário `Authorization` permite apenas uma tentativa de upload deste documento dentro de 10 minutos. A URL, por si só, não concede acesso. Nunca substitua esse cabeçalho por uma chave de API do workspace ou um token OAuth, inclua segredos em uma URL, siga redirecionamentos ou registre os cabeçalhos temporários em logs. O segredo de upload não pode ler documentos, criar traduções nem aprovar gastos. Revogar a conexão ou remover sua permissão invalida as capacidades de upload ainda não utilizadas.

A quantidade de bytes recebidos deve corresponder a `size_bytes`. O limite de cada formato é verificado antes da emissão da autorização. Crie a tradução em até uma hora. Um workspace pode ter 20 uploads pendentes e criar 120 sessões por hora. Os arquivos não utilizados podem ser removidos após 24 horas e são coletados pela rotina diária de limpeza. Depois que uma tradução passa a usar o arquivo, aplica-se o período normal de retenção. A recuperação por upload\_id fica disponível até a limpeza da sessão, no mínimo 24 horas após a emissão. Guarde o ID do lote para recuperar a tradução do seu histórico depois.

## Requisitos para agentes

O ambiente de execução do agente precisa ter acesso a arquivos locais e um cliente HTTP capaz de enviar solicitações PUT com bytes brutos. O MCP, por si só, não consegue enviar bytes binários, e o AI Glot Code Mode não tem acesso a arquivos locais nem a HTTP de saída. Se esses recursos não estiverem disponíveis, informe claramente ao usuário que o assistente não consegue enviar o anexo. Recomende fazer upload pelo app web do AI Glot, usar a CLI ou fornecer um link de download HTTPS para `file_url`. Nunca afirme que o upload foi concluído sem verificá-lo.

Depois do upload, confira o plano de tradução e as exclusões antes de aprovar o custo em créditos. [Enviar bytes brutos](/docs/api/uploads/send) explica como lidar com novas tentativas e falhas.