> ## 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.

# Início de Upload em Partes Blob

> Esta documentação fornece uma visão abrangente do endpoint POST /v1/objects/chunked da API Blob da SquareCloud.

<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>

Início de upload abre um upload em partes, o fluxo para arquivos acima do limite de 100 MB por requisição única, até **1 GiB**. Ele reserva a chave do objeto e retorna um token `upload` opaco que você carrega pelas três chamadas seguintes: [Envio de parte](/pt-br/blob-reference/endpoint/chunked-part) para enviar cada chunk, [Conclusão do upload](/pt-br/blob-reference/endpoint/chunked-complete) para selar o objeto, e [Cancelamento do upload](/pt-br/blob-reference/endpoint/chunked-abort) para cancelar.

**Não existe sessão no servidor**: o token é todo o estado do upload, então persista-o se o upload atravessar um recarregamento de página. Um cliente que perde o token não consegue cancelar o upload, e os chunks armazenados contam contra o limite de **8 uploads abertos** da conta até que o serviço os recolha (cerca de 24 horas).

O contrato de query é o mesmo do [Envio de objeto](/pt-br/blob-reference/endpoint/post), mais `filename`: não há envelope multipart aqui, então a extensão armazenada precisa vir da query string. O envio exige um plano pago.

<ParamField query="name" type="string" placeholder="File Name" required>
  Uma string representando o nome do arquivo (sem extensão).<br />Deve obedecer ao padrão a a z, A a Z, 0 a 9 e \_ (3 a 32 caracteres).
</ParamField>

<ParamField query="filename" type="string" placeholder="Original filename">
  O nome original do arquivo, com extensão (por exemplo, `reads.fastq.gz`). A extensão armazenada é derivada dele, com fallback para o parâmetro `mime_type` e depois para `bin`.
</ParamField>

<ParamField query="prefix" type="string" placeholder="File Prefix">
  Uma string representando o prefixo do arquivo.<br />Deve obedecer ao padrão a a z, A a Z, 0 a 9 e \_ (3 a 32 caracteres).
</ParamField>

<ParamField query="expire" type="number" placeholder="Expiration (days)">
  Um número indicando o período de expiração do arquivo, variando de 7 a 1825 dias (5 anos).
</ParamField>

<ParamField query="security_hash" type="boolean" placeholder="Security Hash">
  Defina como true se um hash de segurança for exigido.
</ParamField>

<ParamField query="auto_download" type="boolean" placeholder="Auto Download">
  Defina como true se o arquivo deve ser marcado para download automático.
</ParamField>

### Limites

<Note>
  * Tamanho do objeto: até **1 GiB** (1.073.741.824 bytes).
  * Tamanho do chunk: **mínimo de 5 MB**, **máximo de 32 MB** (o último chunk pode ser menor).
  * Chunks por objeto: **205** (os números de parte vão de 1 a 205).
  * Uploads abertos por conta: **8** simultâneos (`TOO_MANY_OPEN_UPLOADS`, 429).
  * Limite de requisições: 5 aberturas a cada 10 segundos, com bloqueio de 10 segundos ao exceder isso.

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

### Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida. "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. Carregue-o em todas as chamadas seguintes do fluxo; ele é o único identificador deste upload.
    </ResponseField>

    <ResponseField name="id" type="string">
      O ID (chave) sob o qual o objeto será armazenado.
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome do arquivo.
    </ResponseField>

    <ResponseField name="prefix" type="string">
      O prefixo sob o qual o arquivo será armazenado (`null` quando nenhum foi enviado).
    </ResponseField>

    <ResponseField name="url" type="string">
      A URL pública da CDN em que o objeto será servido depois de concluído.
    </ResponseField>

    <ResponseField name="chunk" type="object">
      Os limites do fluxo em partes: `min_size` e `max_size` (bytes do chunk), `max_parts` e `max_object_size` (bytes totais).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
    --header 'Authorization: SUA_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    name: 'myfile',
    filename: 'reads.fastq.gz',
    expire: '30',
  });

  const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
    method: 'POST',
    headers: { Authorization: 'SUA_API_KEY' },
  });

  const { response: upload } = await response.json();
  // persista upload.upload: ele é o único identificador deste upload
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'SUA_API_KEY'},
      params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
  )
  upload = response.json()['response']
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
      "id": "3155597145698959364/myfile-ex30.fastq.gz",
      "name": "myfile",
      "prefix": null,
      "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
      "chunk": {
        "min_size": 5242880,
        "max_size": 33554432,
        "max_parts": 205,
        "max_object_size": 1073741824
      }
    }
  }
  ```
</ResponseExample>

### Solução de problemas

<Tabs>
  <Tab title="Código 400">
    ### Relacionado ao Objeto

    <CodeGroup>
      ```json NAME theme={null}
      // O nome do objeto fornecido é inválido.
      // Deve obedecer ao padrão a a z, A a Z, 0 a 9 e _.
      {
          "status": "error",
          "code": "INVALID_OBJECT_NAME"
      }
      ```

      ```json PREFIX theme={null}
      // O prefixo do objeto fornecido é inválido.
      // Deve obedecer ao padrão a a z, A a Z, 0 a 9 e _.
      {
          "status": "error",
          "code": "INVALID_OBJECT_PREFIX"
      }
      ```

      ```json EXPIRE theme={null}
      // O valor de expiração fornecido para o objeto é inválido.
      // Deve ser um número entre 7 e 1825. (valor em dias).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json FILETYPE theme={null}
      // A extensão do arquivo está malformada ou é longa demais.
      {
          "status": "error",
          "code": "INVALID_FILE_TYPE"
      }
      ```

      ```json BLOCKED_FILE_TYPE theme={null}
      // Extensões de executáveis/instaladores (exe, msi, bat, apk, ...) não são aceitas.
      {
          "status": "error",
          "code": "BLOCKED_FILE_TYPE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 401">
    ### Não autorizado

    <CodeGroup>
      ```json ACCESS_DENIED theme={null}
      // A chave de API está ausente ou é inválida. Defina uma chave válida no cabeçalho Authorization.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```

      ```json PERMISSION_DENIED theme={null}
      // A conta não possui um plano pago ativo. Enviar arquivos ao Blob Storage exige um plano pago.
      {
          "status": "error",
          "code": "PERMISSION_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 403">
    ### Cota de armazenamento excedida

    <CodeGroup>
      ```json STORAGE_QUOTA_EXCEEDED theme={null}
      // Você excedeu sua cota de armazenamento. Exclua arquivos ou faça upgrade do plano.
      {
          "status": "error",
          "code": "STORAGE_QUOTA_EXCEEDED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 429">
    ### Limite de requisições

    <CodeGroup>
      ```json RATE_LIMITED theme={null}
      // Limite de aberturas atingido (5 aberturas por janela de 10s, bloqueio de 10s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```

      ```json TOO_MANY_OPEN_UPLOADS theme={null}
      // Já existem 8 uploads em partes abertos. Conclua ou cancele um primeiro.
      {
          "status": "error",
          "code": "TOO_MANY_OPEN_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 500">
    ### Falha no upload

    <CodeGroup>
      ```json UPLOAD_FAILED theme={null}
      // Falha ao abrir o upload em partes. Tente novamente mais tarde.
      {
          "status": "error",
          "code": "UPLOAD_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>