> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API di generazione video

> Scegli i percorsi video di CometAPI per i flussi di lavoro di Seedance, HappyHorse, Sora 2, Veo 3, Wan, xAI, Vidu, Omni, Kling e Runway.

Usa la documentazione dei modelli video di CometAPI scegliendo il flusso di lavoro del provider che corrisponde al tuo tipo di attività. La maggior parte degli endpoint video crea task asincroni, quindi salva il task ID e usa il polling per recuperare i risultati. Aggiungi callback solo quando la pagina specifica del modello documenta il supporto per i callback.

## Scegli un'API video

<CardGroup cols={2}>
  <Card title="Crea un video Seedance" icon="sparkles" href="/api/video/seedance/create">
    Crea task video Seedance.
  </Card>

  <Card title="Crea un video HappyHorse" icon="sparkles" href="/api/video/happyhorse/create">
    Crea job text-to-video HappyHorse.
  </Card>

  <Card title="Crea un video Sora 2" icon="film" href="/api/video/sora-2/create">
    Crea job video Sora 2.
  </Card>

  <Card title="Recupera un video Sora 2" icon="refresh" href="/api/video/sora-2/retrieve">
    Interroga i job video di Sora.
  </Card>

  <Card title="Crea un video Veo 3" icon="film" href="/api/video/veo3/create">
    Crea job video Veo.
  </Card>

  <Card title="Crea un video Wan" icon="sparkles" href="/api/video/wan/create">
    Crea job text-to-video Wan.
  </Card>

  <Card title="Crea un video xAI" icon="film" href="/api/video/xai/video-generation">
    Genera job video xAI.
  </Card>

  <Card title="Crea un video Vidu" icon="sparkles" href="/api/video/vidu/create">
    Crea job text-to-video Vidu.
  </Card>

  <Card title="Crea un video Omni (Beta)" icon="sparkles" href="/api/video/omni/create">
    Crea job video Omni beta.
  </Card>

  <Card title="Crea un task Kling text-to-video" icon="film" href="/api/video/kling/text-to-video">
    Genera video Kling da prompt di testo.
  </Card>

  <Card title="Crea un task Runway image-to-video" icon="film" href="/api/video/runway/official-format/runway-images-raw-video">
    Genera video Runway da immagini.
  </Card>
</CardGroup>

## Creare e interrogare un task video

Usa un model ID con capacità video dalla [pagina Modelli](/it/overview/models) o dalla [directory dei modelli](https://www.cometapi.com/models/). Gli esempi qui sotto creano un task video con `POST /v1/videos`, quindi interrogano il task ID restituito finché il task non raggiunge uno stato terminale.

<Note>
  Questi esempi usano il segnaposto `your-video-model-id`. Sostituiscilo con un model ID video disponibile dalla [pagina Modelli](/it/overview/models) o dalla [directory dei modelli](https://www.cometapi.com/models/) prima di eseguire la richiesta.
</Note>

<Tip>
  Apri [Create a Seedance video](/api/video/seedance/create) e [Retrieve a Seedance video](/api/video/seedance/query) per usare i playground API e gli schemi degli endpoint.
</Tip>

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  import requests

  headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}

  create_response = requests.post(
      "https://api.cometapi.com/v1/videos",
      headers=headers,
      data={
          "model": "your-video-model-id",
          "prompt": "A calm camera move across a desk with a paper airplane",
      },
      timeout=30,
  )
  create_response.raise_for_status()
  task = create_response.json()
  task_id = task["id"]

  terminal_statuses = {"completed", "failed", "error"}

  while True:
      poll_response = requests.get(
          f"https://api.cometapi.com/v1/videos/{task_id}",
          headers=headers,
          timeout=30,
      )
      poll_response.raise_for_status()
      result = poll_response.json()
      print(result["status"], result.get("progress"))

      if result["status"] in terminal_statuses:
          print(result.get("video_url"))
          break

      time.sleep(10)
  ```

  ```javascript Node.js theme={null}
  const form = new FormData();
  form.append("model", "your-video-model-id");
  form.append("prompt", "A calm camera move across a desk with a paper airplane");

  const createResponse = await fetch("https://api.cometapi.com/v1/videos", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
    },
    body: form,
  });

  if (!createResponse.ok) {
    throw new Error(await createResponse.text());
  }

  const task = await createResponse.json();
  const terminalStatuses = new Set(["completed", "failed", "error"]);

  while (true) {
    const pollResponse = await fetch(
      `https://api.cometapi.com/v1/videos/${task.id}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
        },
      },
    );

    if (!pollResponse.ok) {
      throw new Error(await pollResponse.text());
    }

    const result = await pollResponse.json();
    console.log(result.status, result.progress);

    if (terminalStatuses.has(result.status)) {
      console.log(result.video_url);
      break;
    }

    await new Promise((resolve) => setTimeout(resolve, 10_000));
  }
  ```

  ```bash cURL theme={null}
  curl https://api.cometapi.com/v1/videos \
    -H "Authorization: Bearer $COMETAPI_KEY" \
    -F "model=your-video-model-id" \
    -F "prompt=A calm camera move across a desk with a paper airplane"

  curl https://api.cometapi.com/v1/videos/task_example \
    -H "Authorization: Bearer $COMETAPI_KEY"
  ```
</CodeGroup>

## Esempi di risposta

Una risposta di creazione riuscita può apparire così. Salva il task ID prima di eseguire il polling:

```json theme={null}
{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "your-video-model-id",
  "status": "queued",
  "progress": 0,
  "created_at": 1779872000
}
```

Una risposta di polling riuscita può apparire così. Le risposte completate possono includere `video_url`; alcuni formati dei provider usano campi risultato specifici del modello o la route del contenuto video quando tale route è documentata:

```json theme={null}
{
  "id": "task_example",
  "object": "video",
  "model": "your-video-model-id",
  "status": "completed",
  "progress": 100,
  "completed_at": 1779872300,
  "video_url": "https://example.com/generated-video.mp4"
}
```

## Esempi di record dei modelli

<Info>
  Questa risposta di esempio del catalogo modelli mostra l'envelope di `/api/models` e la forma di un record di modello video. Non è un elenco completo dei modelli.
</Info>

```bash cURL theme={null}
curl https://api.cometapi.com/api/models
```

```json theme={null}
{
  "success": true,
  "page": 1,
  "page_size": 20,
  "total": 302,
  "data": [
    {
      "created": 1767529753,
      "id": "your-video-model-id",
      "code": "your-video-model-id",
      "provider": "ExampleProvider",
      "provider_code": "example",
      "name": "Example video model",
      "model_type": "video",
      "features": [
        "text-to-video"
      ],
      "endpoints": "{\n  \"seedance\": {\n    \"path\": \"/v1/videos\",\n    \"method\": \"POST\"\n  }\n}",
      "pricing": {
        "currency": "USD / M Tokens",
        "input": null,
        "output": null,
        "per_request": null,
        "per_second": 0.024
      }
    }
  ]
}
```

## Errori comuni

<AccordionGroup>
  <Accordion title="ID attività mancante">
    Salva l'ID dalla risposta di creazione prima di restituire il controllo dal tuo job handler.
  </Accordion>

  <Accordion title="Polling troppo veloce">
    Aggiungi un ritardo e un backoff tra i controlli dello stato.
  </Accordion>

  <Accordion title="Durata o dimensione non supportata">
    Usa i campi di durata e risoluzione documentati per l'endpoint video selezionato.
  </Accordion>

  <Accordion title="video_url mancante">
    Tratta `video_url` come opzionale e usa come fallback i campi di risultato specifici del modello o la route dei contenuti quando disponibile.
  </Accordion>

  <Accordion title="Callback non ricevuta">
    Usa il polling come fonte di verità e verifica che il tuo URL di callback accetti richieste POST.
  </Accordion>
</AccordionGroup>

## Codici di errore e strategia di retry

<AccordionGroup>
  <Accordion title="400">
    Non eseguire il retry finché i campi prompt, file, durata o dimensione non sono stati corretti.
  </Accordion>

  <Accordion title="401">
    Non eseguire il retry finché la chiave API non è presente e valida.
  </Accordion>

  <Accordion title="404">
    Controlla l'ID attività, il base URL, il path e il model ID prima di eseguire il retry.
  </Accordion>

  <Accordion title="413">
    Riduci la dimensione dell'upload prima di eseguire il retry.
  </Accordion>

  <Accordion title="429">
    Esegui il retry con backoff esponenziale e riduci la concorrenza di creazione o di polling.
  </Accordion>

  <Accordion title="500 or 503">
    Esegui il retry della creazione dell'attività con backoff; continua a fare polling delle attività esistenti a meno che l'attività non raggiunga un errore terminale.
  </Accordion>
</AccordionGroup>

<Tip>
  Per i pattern di implementazione, vedi [Codici di errore e strategia di retry](/it/guides/error-codes-and-retry-strategy), [Limiti di frequenza e concorrenza](/it/guides/rate-limits-and-concurrency), e [Webhook e polling per la generazione video](/it/guides/webhook-and-polling-for-video-generation).
</Tip>

## Prezzi e directory dei modelli

<CardGroup cols={3}>
  <Card title="Pagina dei modelli" icon="list" href="/overview/models">
    Scopri come CometAPI espone i model ID nella documentazione.
  </Card>

  <Card title="Directory dei modelli" icon="puzzle-piece" href="https://www.cometapi.com/models/">
    Esplora disponibilità e capacità dei modelli.
  </Card>

  <Card title="Prezzi" icon="tag" href="https://www.cometapi.com/pricing/">
    Controlla i prezzi prima di chiamare un modello.
  </Card>
</CardGroup>