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

# Envio de Objeto Blob

> Esta documentação fornece uma visão abrangente do endpoint POST /v1/objects 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>

<ParamField body="file" type="file" placeholder="myphone.png" required>
  Use FormData. (multipart/form-data)
</ParamField>

<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-z, A-Z, 0-9 e \_ (3 a 32 caracteres).
</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 1 a 365 dias.
</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 e uploads simultâneos

<Note>
  O envio de arquivos exige um plano pago.

  * Planos **Hobby** e **Standard** são limitados a **1 upload por segundo**.
  * Planos **Pro** e **Enterprise** **não** têm o limite por segundo — em vez disso, podem realizar até **4 uploads ao mesmo tempo**.

  Em todos os planos pagos, uma conta pode ter no máximo **4 uploads em andamento simultaneamente**. Iniciar outro upload enquanto 4 ainda estão em execução retorna `TOO_MANY_CONCURRENT_UPLOADS` (429).
</Note>

<Info>
  Por segurança, arquivos `.html` e `.svg` são sempre entregues como download (servidos como `application/octet-stream`) em vez de renderizados inline.
</Info>

### 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="id" type="string">
      O ID do arquivo enviado.
    </ResponseField>

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

    <ResponseField name="size" type="number">
      O tamanho do arquivo enviado, em bytes.
    </ResponseField>

    <ResponseField name="url" type="string">
      A URL do arquivo. (Arquivo distribuído na CDN da Square Cloud)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
    --header 'Authorization: SUA_API_KEY' \
    --form 'file=@./myphone.png'
  ```

  ```javascript JavaScript theme={null}
  import fs from 'node:fs';

  const form = new FormData();
  form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

  const params = new URLSearchParams({
    name: 'myfile',
    prefix: 'images',
    expire: '30',
  });

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

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

  with open('myphone.png', 'rb') as f:
      response = requests.post(
          'https://blob.squarecloud.app/v1/objects',
          headers={'Authorization': 'SUA_API_KEY'},
          params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
          files={'file': ('myphone.png', f, 'image/png')},
      )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
      "status": "success",
      "response": {
          "id": "3155597145698959364/test_lxch4k7y-07ee.png",
          "name": "test",
          "size": 416230,
          "url": "https://public-blob.squarecloud.dev/3155597145698959364/test_lxch4k7y-07ee.png"
      }
  }
  ```
</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 1 e 365. (valor em dias).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json SECURITY_HASH theme={null}
      // O booleano de hash de segurança fornecido é inválido.
      // Deve ser apenas true ou false.
      {
          "status": "error",
          "code": "INVALID_OBJECT_SECURITY_HASH"
      }
      ```

      ```json AUTO_DOWNLOAD theme={null}
      // O booleano de download automático fornecido é inválido.
      // Deve ser apenas true ou false.
      {
          "status": "error",
          "code": "INVALID_OBJECT_AUTO_DOWNLOAD"
      }
      ```
    </CodeGroup>

    ### Relacionado ao Arquivo

    <Info>O tamanho máximo de arquivo atualmente é 100MB. No futuro, planejamos aumentar para 10GB. Por enquanto, o limite é 100MB devido a restrições técnicas e de balanceamento.</Info>

    <CodeGroup>
      ```json INVALID_FILE theme={null}
      // O arquivo fornecido é inválido.
      {
          "status": "error",
          "code": "INVALID_FILE"
      }
      ```

      ```json FILETYPE theme={null}
      // O tipo de arquivo fornecido é inválido.
      {
          "status": "error",
          "code": "INVALID_FILETYPE"
      }
      ```

      ```json FILE_TOO_SMALL theme={null}
      // O tamanho do arquivo é pequeno demais (< 1KB).
      {
          "status": "error",
          "code": "FILE_TOO_SMALL"
      }
      ```

      ```json FILE_TOO_LARGE theme={null}
      // O tamanho do arquivo é grande demais (> 100MB).
      {
          "status": "error",
          "code": "FILE_TOO_LARGE"
      }
      ```
    </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.
      // Também retornado quando a conta está no plano gratuito — o envio exige um plano pago.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```json RATELIMIT theme={null}
      // Limite de uploads por segundo atingido (Hobby/Standard: máx. 1 upload por segundo).
      {
          "status": "error",
          "code": "RATELIMIT"
      }
      ```

      ```json TOO_MANY_CONCURRENT_UPLOADS theme={null}
      // Uploads simultâneos demais (máx. 4 em andamento ao mesmo tempo por conta).
      {
          "status": "error",
          "code": "TOO_MANY_CONCURRENT_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>