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

# Blob Chunked Upload Init

> Cette documentation fournit une vue d'ensemble complète de l'endpoint POST /v1/objects/chunked de l'API Blob de SquareCloud.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clé d'API de votre compte. Vous pouvez la trouver dans les [paramètres de votre compte](https://squarecloud.app/fr/account/security).
</ParamField>

Chunked Init ouvre un upload chunked, le flux destiné aux fichiers au-dessus du plafond de 100 Mo par requête unique, jusqu'à **1 GiB**. Il réserve la clé de l'objet et renvoie un jeton `upload` opaque que vous transmettez aux trois appels suivants : [Chunked Part](/fr/blob-reference/endpoint/chunked-part) pour envoyer chaque chunk, [Chunked Complete](/fr/blob-reference/endpoint/chunked-complete) pour sceller l'objet, et [Chunked Abort](/fr/blob-reference/endpoint/chunked-abort) pour annuler.

Il n'y a **aucune session côté serveur** : le jeton constitue l'intégralité de l'état de l'upload, donc conservez-le si l'upload doit survivre à un rechargement de page. Un client qui perd son jeton ne peut pas annuler l'upload, et les chunks stockés comptent dans la limite de **8 uploads ouverts** du compte jusqu'à ce que le service les récupère (environ 24 heures).

Le contrat de la query est le même que pour [Object Post](/fr/blob-reference/endpoint/post), plus `filename` : il n'y a pas d'enveloppe multipart ici, donc l'extension stockée doit provenir de la query string. L'upload nécessite un plan payant.

<ParamField query="name" type="string" placeholder="File Name" required>
  Une chaîne représentant le nom du fichier. (sans extension)<br />Doit respecter le motif a à z, A à Z, 0 à 9 et \_. (3 à 32 caractères)
</ParamField>

<ParamField query="filename" type="string" placeholder="Original filename">
  Le nom de fichier d'origine, extension incluse (par exemple `reads.fastq.gz`). L'extension stockée en est dérivée, avec repli sur le paramètre `mime_type`, puis sur `bin`.
</ParamField>

<ParamField query="prefix" type="string" placeholder="File Prefix">
  Une chaîne représentant le préfixe du fichier.<br />Doit respecter le motif a à z, A à Z, 0 à 9 et \_. (3 à 32 caractères)
</ParamField>

<ParamField query="expire" type="number" placeholder="Expiration (days)">
  Un nombre indiquant la période d'expiration du fichier, comprise entre 7 et 1825 jours (5 ans).
</ParamField>

<ParamField query="security_hash" type="boolean" placeholder="Security Hash">
  Définissez sur true si un hash de sécurité est requis.
</ParamField>

<ParamField query="auto_download" type="boolean" placeholder="Auto Download">
  Définissez sur true si le fichier doit être configuré pour un téléchargement automatique.
</ParamField>

### Limites

<Note>
  * Taille de l'objet : jusqu'à **1 GiB** (1 073 741 824 octets).
  * Taille des chunks : **5 Mo minimum**, **32 Mo maximum** (le dernier chunk peut être plus petit).
  * Chunks par objet : **205** (les numéros de part vont de 1 à 205).
  * Uploads ouverts par compte : **8** simultanés (`TOO_MANY_OPEN_UPLOADS`, 429).
  * Limite de débit : 5 ouvertures par 10 secondes, avec un blocage de 10 secondes au-delà.

  Lisez les limites depuis l'objet `chunk` de la réponse plutôt que de les coder en dur.
</Note>

### Réponse

<ResponseField name="status" type="string">
  Indique si l'appel a réussi. "success" en cas de succès, "error" sinon.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Afficher l'objet">
    <ResponseField name="upload" type="string">
      Le jeton `upload` opaque. Transmettez-le à chaque appel ultérieur du flux ; c'est le seul point d'accès à cet upload.
    </ResponseField>

    <ResponseField name="id" type="string">
      L'ID (clé) sous lequel l'objet sera stocké.
    </ResponseField>

    <ResponseField name="name" type="string">
      Le nom du fichier.
    </ResponseField>

    <ResponseField name="prefix" type="string">
      Le préfixe sous lequel le fichier sera stocké (`null` lorsqu'aucun n'a été envoyé).
    </ResponseField>

    <ResponseField name="url" type="string">
      L'URL CDN publique depuis laquelle l'objet sera servi une fois finalisé.
    </ResponseField>

    <ResponseField name="chunk" type="object">
      Les limites du flux chunked : `min_size` et `max_size` (octets par chunk), `max_parts` et `max_object_size` (octets au total).
    </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: YOUR_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: 'YOUR_API_KEY' },
  });

  const { response: upload } = await response.json();
  // persist upload.upload — it is the only handle to this upload
  ```

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

  response = requests.post(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'YOUR_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>

### Dépannage

<Tabs>
  <Tab title="Code de statut 400">
    ### Lié à l'objet

    <CodeGroup>
      ```json NAME theme={null}
      // The provided object name is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_NAME"
      }
      ```

      ```json PREFIX theme={null}
      // The provided object prefix is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_PREFIX"
      }
      ```

      ```json EXPIRE theme={null}
      // The provided expiration value for the object is invalid.
      // Must be a number ranging from 7 to 1825. (value in days).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json FILETYPE theme={null}
      // The file extension is malformed or too long.
      {
          "status": "error",
          "code": "INVALID_FILE_TYPE"
      }
      ```

      ```json BLOCKED_FILE_TYPE theme={null}
      // Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
      {
          "status": "error",
          "code": "BLOCKED_FILE_TYPE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Code de statut 401">
    ### Non autorisé

    <CodeGroup>
      ```json ACCESS_DENIED theme={null}
      // The API key is missing or invalid. Set a valid key in the Authorization header.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```

      ```json PERMISSION_DENIED theme={null}
      // The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
      {
          "status": "error",
          "code": "PERMISSION_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Code de statut 403">
    ### Quota de stockage dépassé

    <CodeGroup>
      ```json STORAGE_QUOTA_EXCEEDED theme={null}
      // You have exceeded your storage quota. Delete some files or upgrade your plan.
      {
          "status": "error",
          "code": "STORAGE_QUOTA_EXCEEDED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Code de statut 429">
    ### Limite de débit atteinte

    <CodeGroup>
      ```json RATE_LIMITED theme={null}
      // Init rate limit reached (5 opens per 10s window, blocked for 10s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```

      ```json TOO_MANY_OPEN_UPLOADS theme={null}
      // 8 chunked uploads already open. Complete or abort one first.
      {
          "status": "error",
          "code": "TOO_MANY_OPEN_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Code de statut 500">
    ### Échec de l'upload

    <CodeGroup>
      ```json UPLOAD_FAILED theme={null}
      // Failed to open the chunked upload. Please try again later.
      {
          "status": "error",
          "code": "UPLOAD_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>