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

# Démarrage rapide de l'API Blob Storage

> Envoyez et téléchargez votre premier fichier avec l'API Blob Storage : URL de base v1, en-tête Authorization, envoi curl, réponse et lien de téléchargement.

Blob Storage conserve vos fichiers, sert les fichiers publics depuis un CDN et fournit des liens vers les fichiers privés. Cette page vous emmène d'une clé API à un fichier envoyé et à un lien de téléchargement, avec `curl`. Le stockage est inclus dans chaque plan : consultez [Blob Storage](/fr/services/blob) pour les plans, les prix et la FAQ.

## URL de base

Chaque endpoint de cette référence est relatif à :

```bash theme={"system"}
https://blob.squarecloud.app/v1
```

## Authentification

Blob Storage accepte les mêmes clés API que l'[API Square Cloud](/fr/api-reference/introduction), dans l'en-tête `Authorization`. La clé a besoin du scope `blob:write` pour envoyer et de `blob:read` pour lister et télécharger, et elle ne peut pas être restreinte à des applications précises. Créez-en une dans les [paramètres de sécurité de votre compte](https://squarecloud.app/fr/account/security) et gardez-la dans une variable d'environnement :

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"
```

Pour en savoir plus sur les scopes et les jetons d'envoi, consultez [Authentification](/fr/blob-reference/authentication).

## Envoyer un fichier

[Object Post](/fr/blob-reference/endpoint/post) reçoit le fichier en `multipart/form-data` et son nom, sans extension, dans la query :

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}
```

Le fichier est public par défaut : `url` fonctionne immédiatement dans un navigateur ou une balise `<img>`. Conservez l'`id` tel quel, car toutes les autres routes l'utilisent.

Une seule requête accepte des fichiers de 512 octets à 100 Mo. Les fichiers plus volumineux, jusqu'à 10 GiB, passent par l'[envoi chunked](/fr/blob-reference/endpoint/chunked-init) ou par la [passerelle S3](/fr/blob-reference/s3-compatibility).

## Envoyer un fichier privé

Ajoutez `private=true` et le fichier n'a pas d'URL publique (`url` vaut `null`) :

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'
```

## Télécharger un fichier

Un fichier public se télécharge depuis son `url`. Pour un fichier privé, [Téléchargement d'objet](/fr/blob-reference/endpoint/download) signe un lien temporaire qui fonctionne sans identifiants et redirige vers lui, donc `curl -L` enregistre le fichier :

```bash theme={"system"}
curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

Remplacez `<id>` par l'`id` de l'envoi. Ajoutez `redirect=false` pour obtenir le lien en JSON et le transmettre à quelqu'un d'autre. Pour des liens révocables ou protégés par un mot de passe, créez un [lien de partage](/fr/blob-reference/endpoint/shares-create).

## Lister et supprimer des fichiers

[Liste d'objets](/fr/blob-reference/endpoint/list) renvoie vos fichiers page par page :

```bash theme={"system"}
curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

[Suppression d'objets](/fr/blob-reference/endpoint/delete) supprime un fichier, ou jusqu'à 100 en une seule requête :

```bash theme={"system"}
curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'
```

## En cas d'échec

Les erreurs arrivent sous la forme `{ "status": "error", "code": "..." }`. Celles que vous risquez de rencontrer en premier :

| Code | HTTP | Solution |
| - | - | - |
| `ACCESS_DENIED` | 401 | La clé est manquante ou n'est pas reconnue. Vérifiez l'en-tête `Authorization`. |
| `PERMISSION_DENIED` | 401 | Le compte n'a pas de plan actif, il ne peut donc pas envoyer de fichiers. |
| `MISSING_SCOPE` | 403 | La clé n'a pas `blob:write` ou `blob:read`. Créez une clé avec ce scope. |
| `RESOURCE_NOT_ALLOWED` | 403 | La clé est restreinte à des applications. Utilisez une clé sans cette restriction. |
| `FILE_TOO_LARGE` | 413 | Le fichier dépasse 100 Mo. Utilisez l'envoi chunked. |

Tous les codes figurent dans [Erreurs](/fr/blob-reference/errors).

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="SDK Blob" icon="js" href="/fr/sdks/blob/client">
    Envoyez et gérez des fichiers depuis JavaScript, avec les envois chunked gérés pour vous.
  </Card>

  <Card title="Compatibilité S3" icon="bucket" href="/fr/blob-reference/s3-compatibility">
    Utilisez aws-cli, boto3, rclone ou n'importe quel SDK AWS.
  </Card>

  <Card title="Liens et partage" icon="share-nodes" href="/fr/blob-reference/links-and-sharing">
    Liens temporaires, liens de partage et quand utiliser chacun.
  </Card>

  <Card title="Envoyer depuis le navigateur" icon="upload" href="/fr/blob-reference/endpoint/upload-tokens">
    Laissez les visiteurs envoyer des fichiers sans exposer votre clé API.
  </Card>
</CardGroup>