> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Iniciar um upload em partes

> Abra um upload em partes para arquivos de até 10 GiB com POST /v1/objects/chunked e obtenha o token de upload para as próximas chamadas.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

O Início de Upload em Partes abre um upload em partes, o fluxo para arquivos acima do limite de 100 MB por requisição, até **10 GiB**. Ele retorna um token `upload` opaco que você carrega pelas próximas chamadas:

<Steps>
  <Step title="Iniciar">Esta rota. Guarde o token `upload`.</Step>
  <Step title="Enviar as partes">[Enviar Parte](/pt-br/blob-reference/endpoint/chunked-part), em qualquer ordem, até 6 ao mesmo tempo.</Step>
  <Step title="Concluir">O [Concluir Upload](/pt-br/blob-reference/endpoint/chunked-complete) finaliza o arquivo. Ou use o [Cancelar Upload](/pt-br/blob-reference/endpoint/chunked-abort) para cancelar.</Step>
</Steps>

Não há sessão no servidor: o token é todo o estado do upload, então guarde-o se o upload puder atravessar um recarregamento de página. Perdeu o token? O [Uploads Abertos](/pt-br/blob-reference/endpoint/chunked-open) lista os uploads abertos com os seus tokens, e o [Status do Upload](/pt-br/blob-reference/endpoint/chunked-status) informa quais partes já chegaram. Uploads parados por 24 horas são cancelados automaticamente.

## Parâmetros

Os parâmetros de query são os mesmos do [Envio de Objeto](/pt-br/blob-reference/endpoint/post), mais `filename` e `mime_type`: aqui não há envelope multipart, então a extensão precisa vir da query. Exige o escopo `blob:write`, ou um [token de upload](/pt-br/blob-reference/endpoint/upload-tokens), e um plano ativo.

<ParamField query="name" type="string" placeholder="dataset" required>
  O nome do arquivo, sem extensão. Mesmo padrão do Envio de Objeto.
</ParamField>

<ParamField query="filename" type="string" placeholder="reads.fastq.gz">
  O nome original do arquivo, com extensão. A extensão armazenada vem dele, depois de `mime_type` e, por fim, cai para `bin`.
</ParamField>

<ParamField query="mime_type" type="string" placeholder="application/gzip">
  Usado para a extensão apenas quando `filename` não tem uma.
</ParamField>

<ParamField query="prefix" type="string">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="private" type="boolean">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="expire" type="string">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="security_hash" type="boolean">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="overwrite" type="boolean">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="disposition" type="string">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="auto_download" type="boolean">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="cache_control" type="string">
  Igual ao do Envio de Objeto.
</ParamField>

<ParamField query="metadata" type="string">
  Igual ao do Envio de Objeto.
</ParamField>

## Limites

<Note>
  * Tamanho do arquivo: até **10 GiB** (10.737.418.240 bytes), ou menos quando uma regra ou um token de upload define um limite menor.
  * Tamanho da parte: **mínimo de 5 MB** (5.242.880 bytes), **máximo de 32 MB** (33.554.432 bytes). A última parte pode ser menor.
  * Partes por arquivo: até **2048**.
  * Uploads abertos por conta: **32**, contando os uploads abertos pelo [gateway S3](/pt-br/blob-reference/s3-compatibility) (`TOO_MANY_OPEN_UPLOADS`, 429).
  * Limite de taxa: 5 aberturas a cada 10 segundos.
  * Uma conta que já passou do armazenamento incluído não pode abrir uploads (`STORAGE_QUOTA_EXCEEDED`).

  Leia os limites do objeto `chunk` da resposta em vez de fixá-los no código.
</Note>

## Resposta

<ResponseField name="status" type="string">
  "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="upload" type="string">
      O token de upload opaco. Envie-o em todas as chamadas seguintes do fluxo.
    </ResponseField>

    <ResponseField name="id" type="string">
      O id que o arquivo terá depois de concluído.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Se o arquivo será privado.
    </ResponseField>

    <ResponseField name="url" type="string | null">
      A URL pública que o arquivo terá, ou `null` quando privado.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Quando o arquivo será excluído. Presente apenas quando ele expira.
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome enviado na requisição.
    </ResponseField>

    <ResponseField name="prefix" type="string">
      O prefixo, quando um foi enviado.
    </ResponseField>

    <ResponseField name="chunk" type="object">
      Os limites deste upload: `min_size` e `max_size` (bytes da parte), `max_parts` e `max_object_size` (bytes do arquivo).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={"system"}
  const params = new URLSearchParams({
    name: 'dataset',
    filename: file.name,
    prefix: 'genomics',
    private: 'true',
  });

  const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
    method: 'POST',
    headers: { Authorization: 'YOUR_API_KEY' },
  });
  const { response: upload } = await res.json();
  // persist upload.upload: it is the handle to this upload
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'YOUR_API_KEY'},
      params={'name': 'dataset', 'filename': 'reads.fastq.gz', 'prefix': 'genomics', 'private': 'true'},
  )
  upload = response.json()['response']
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"system"}
  {
    "status": "success",
    "response": {
      "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk",
      "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
      "private": true,
      "url": null,
      "name": "dataset",
      "prefix": "genomics",
      "chunk": {
        "min_size": 5242880,
        "max_size": 33554432,
        "max_parts": 2048,
        "max_object_size": 10737418240
      }
    }
  }
  ```
</ResponseExample>

## Erros

| Código | HTTP | Quando |
| - | - | - |
| `INVALID_OBJECT_*` / `INVALID_STORAGE_AUTO_DOWNLOAD` | 400 | Um parâmetro é inválido, como no [Envio de Objeto](/pt-br/blob-reference/endpoint/post). |
| `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED` | 400 | A extensão está malformada, bloqueada ou não é permitida pela regra ou pelo token. |
| `PERMISSION_DENIED` | 401 | A conta não tem um plano ativo. |
| `UPLOAD_TOKEN_USED` | 401 | O token de upload não tem mais usos. Um token expirado responde `ACCESS_DENIED`. |
| `STORAGE_QUOTA_EXCEEDED` | 403 | A conta já passou do armazenamento incluído. |
| `PREFIX_NOT_ALLOWED` | 403 | O token de upload está vinculado a outro prefixo. |
| `UPGRADE_REQUIRED` | 403 | Uma opção exige um plano superior. |
| `TOO_MANY_OPEN_UPLOADS` | 429 | A conta tem 32 uploads abertos. Conclua ou cancele um. |
| `RATE_LIMITED` | 429 | Mais de 5 aberturas em 10 segundos. |
| `UPLOAD_FAILED` | 500 | O upload não pôde ser aberto. Tente novamente. |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | O armazenamento está temporariamente indisponível. Tente novamente. |

## Relacionados

* SDK do Blob: [`blob.put()`](/pt-br/sdks/blob/uploads) executa todo o fluxo em partes para arquivos acima de 90 MiB


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.