> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Traitement batch

> API de traitement batch pour la génération en masse de lip sync IA. Traitez jusqu'à 500 vidéos en une seule opération avec webhooks et suivi de statut.

L'API Batch de Sync Labs traite jusqu'à 500 générations de lip sync dans une seule requête à l'aide d'un fichier JSONL. C'est idéal pour les workflows de traitement vidéo en masse, comme les campagnes vidéo personnalisées, la localisation de contenu, ou tout scénario qui exige une génération de lip sync à grand volume.

## Quel est le format de fichier batch ?

Le traitement batch vous permet d'envoyer 20 à 500 générations sans gérer vous-même la file d'attente ni la concurrence, avec un délai cible de 24 heures. Les jobs batch contournent votre limite de concurrence normale par génération, mais l'API Batch n'est disponible que sur les plans Scale et Enterprise. À ce jour, seules les générations avec des entrées allant jusqu'à 30 secondes sont prises en charge en traitement batch.

> **Note**
>
> API de lots est disponible uniquement pour les utilisateurs Scale et Enterprise

## Limites de concurrence batch

Les jobs batch contournent votre limite de concurrence normale par génération, mais une limite séparée plafonne le nombre de batchs que vous pouvez exécuter en même temps, selon votre plan. Si vous envoyez un nouveau batch alors que vous êtes déjà à cette limite, l'API renvoie une réponse `429 Too Many Requests`.

Le corps de la 429 est un objet JSON qui décrit la limite atteinte :

```json
{
  "statusCode": 429,
  "errorCode": "concurrency_limit_reached",
  "message": "Batch concurrency limit reached. Please wait for an existing batch to complete or upgrade your plan.",
  "activeBatches": 3,
  "concurrencyLimit": 3,
  "retryAfterSeconds": 20
}
```

La réponse inclut aussi un en-tête `Retry-After` (en secondes) et un en-tête `X-Sync-Concurrency-Limit`. Plutôt que de réessayer immédiatement, attendez `retryAfterSeconds` avant de renvoyer, ou attendez qu'un de vos batchs en cours se termine.

## Comment créer un job batch ?

#### Préparer votre fichier d'entrée

Créez un fichier JSON Lines (.jsonl) avec vos requêtes de génération. Chaque ligne doit contenir un `request_id` unique, l'`endpoint` (doit être `"/v2/generate"`), et un `payload` avec le format standard de requête de génération (identique à celui de la [API de génération](/api-reference/api/generate-api/create)). Le fichier doit être au format JSON Lines (.jsonl) avec un minimum de 20 enregistrements, une taille maximale de 5MB, et jusqu'à 500 requêtes par batch.

**`input.jsonl`**

```jsonl input.jsonl
{"request_id": "request-1", "endpoint": "/v2/generate", "payload": {"model": "lipsync-2", "input": [{"type": "video", "url": "https://assets.sync.so/docs/example-video.mp4"}, {"type": "audio", "url": "https://assets.sync.so/docs/example-audio.wav"}]}}
{"request_id": "request-2", "endpoint": "/v2/generate", "payload": {"model": "lipsync-2", "input": [{"type": "video", "url": "https://assets.sync.so/docs/example-video.mp4"}, {"type": "audio", "url": "https://assets.sync.so/docs/example-audio.wav"}]}}
```

#### Créer un batch

```python
from sync import Sync

sync = Sync()

batch = sync.batch.create(
    input=open("input.jsonl", "rb")
)

print(f"Batch created with ID: {batch.id}")
```

```typescript
import { SyncClient } from "@sync.so/sdk";

const client = new SyncClient();

const batch = await client.batch.create(fs.createReadStream("input.jsonl"));

console.log('Batch created with ID:', batch.id)
```

**`curl`**

```bash curl
curl -X POST https://api.sync.so/v2/batch \
     -H "x-api-key: <your-api-key>" \
     -H "Content-Type: multipart/form-data" \
     -F input=@<input.jsonl>
```

**Paramètres optionnels :**

* `webhook_url`: Recevoir des notifications quand le batch est terminé
* `dry_run`: Définir `true` pour valider votre fichier d'entrée sans lancer le traitement

#### Vérifier le statut du batch

Suivez la progression de votre batch en interrogeant son statut :

**`Check batch status`**

```python Check batch status
batch = sync.batch.get(batch_id)
print(f"Status: {batch.status}")
print(f"Progress: {batch.metrics}")
```

```typescript
const batch = await client.batch.get(batch_id);
console.log('Status:', batch.status);
console.log('Progress:', batch.metrics);
```

```bash
curl https://api.sync.so/v2/batch/<batch_id> \
     -H "x-api-key: <your-api-key>"
```

Un batch peut avoir l'un des statuts suivants :

1. **`PENDING`**: Batch créé, en attente de démarrage du traitement
2. **`PROCESSING`**: Les générations sont en cours de traitement
3. **`COMPLETED`**: Toutes les générations sont terminées (avec succès ou échec)
4. **`FAILED`**: Le traitement batch a totalement échoué

#### Vérifier les résultats du batch

Quand un batch se termine, les résultats sont disponibles sous forme de fichier JSON Lines à l'adresse `outputUrl` de la réponse get batch. Un `GET` vers cette URL renvoie une redirection `302` vers un fichier de résultats signé, les clients qui suivent automatiquement les redirections peuvent lire directement la réponse JSONL. Chaque ligne contient :

**`output.jsonl`**

```jsonl output.jsonl
{"request_id": "request-1", "endpoint": "/v2/generate", "payload": {...}, "status": "COMPLETED", "error": null, "response": {...}, "updated_at": "2024-01-15T10:35:00Z"}
{"request_id": "request-2", "endpoint": "/v2/generate", "payload": {...}, "status": "FAILED", "error": {"code": "INVALID_INPUT", "message": "..."}, "response": null, "updated_at": "2024-01-15T10:35:00Z"}
```

Le champ `response` contient les mêmes données que les réponses individuelles de la [API de génération](/api-reference/api/generate-api/create).

Pour un exemple complet et fonctionnel, consultez l'[exemple de traitement batch](https://github.com/synchronicity-labs/sync-examples/tree/main/batch-processing/python) dans notre dépôt d'exemples.

## Notifications webhook

Lorsque vous fournissez un `webhook_url`, vous recevrez des notifications POST à la fin du batch :

**`webhook_payload.json`**

```json webhook_payload.json
{
  "id": "batch_abc123",
  "createdAt": "2024-01-15T10:30:00Z",
  "status": "COMPLETED",
  "webhookUrl": "https://your-webhook-url.com/batch-webhook",
  "metrics": {
    "totalGenerations": 5,
    "successCount": 4,
    "failedCount": 1,
    "pendingCount": 0
  },
  "options": {},
  "outputUrl": "https://api.sync.so/v2/batches/batch_abc123/result"
}
```