> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Crea esecuzione del template

POST https://api.elevenlabs.io/v1/flows/templates/{template_id}/runs
Content-Type: application/json

Avvia un'esecuzione di un template dei flussi. Passa `version_id` per fissare uno snapshot oppure omettilo o passa `latest` per eseguire l'ultima versione pubblicata. Imposta i valori di input in `inputs`, indicizzati in base all'ID della porta di input. La risposta è l'esecuzione nel suo stato iniziale, con ogni output già elencato in `outputs` sotto il relativo ID porta. Includi `webhook` per ricevere un evento `flows_template_run` contenente l'esecuzione completata quando il suo `status` è `completed` o `failed`; questo è il metodo consigliato per attendere. Senza webhook, recupera `GET /v1/flows/templates/{template_id}/runs/{run_id}` a intervalli moderati finché il `status` non è terminale.

Reference: https://elevenlabs.io/docs/api-reference/flows/templates/runs/create

## Servers

- `https://api.elevenlabs.io` (Production, default)
- `https://api.us.elevenlabs.io` (Production US)
- `https://api.eu.residency.elevenlabs.io` (Production EU)
- `https://api.in.residency.elevenlabs.io` (Production India)
- `https://api.sg.residency.elevenlabs.io` (Production Singapore)

## Request

### Path parameters

- `template_id` (string, required) — L'ID del template, come mostrato nell'app ElevenLabs o da `GET /v1/flows/templates`.

### Body (application/json)

This endpoint expects a TemplateRunCreateRequest.

- `inputs` (map from string to TemplateRunInput, required) — Valori di input indicizzati dall'ID della porta di input. Deve essere specificata ogni porta di input della versione in esecuzione; un ID mancante o sconosciuto viene rifiutato. Passa `{}` per un template senza input.
- `version_id` (string, optional, nullable) — Lo snapshot del template da eseguire. Passa un ID versione specifico per fissare quello snapshot, oppure `latest` (il valore predefinito se omesso) per eseguire la versione pubblicata più di recente del template. Possono essere fissate solo versioni pubblicate, tranne dal proprietario del template, che può fissare anche uno snapshot salvato non pubblicato per provarlo prima della pubblicazione. La bozza live non viene mai eseguita tramite questa API.
- `webhook` (WebhookTarget, optional, nullable) — Includi questa opzione per inviare il risultato dell'esecuzione ai webhook dei flussi configurati nel workspace quando il relativo `status` raggiunge `completed` o `failed`. Un evento per l'intera esecuzione: i `data` dell'evento `flows_template_run` corrispondono alla risposta finale di `GET /v1/flows/templates/{template_id}/runs/{run_id}`.

## Response

### 200

Risposta riuscita

- `id` (string, required) — L'identificatore univoco dell'esecuzione.
- `template_id` (string, required) — Il template eseguito da questa run, così un consumer webhook che esegue più template può distinguere le rispettive run senza mantenere una mappa tra run e template.
- `version_id` (string, required) — La versione del template eseguita da questa run. Viene risolta alla creazione della run, quindi una run avviata con `latest` registra la versione concreta eseguita.
- `status` (enum, required) — Lo stato dell'esecuzione, aggregato dai relativi output: `pending` finché non inizia un output, `generating` mentre un output non è completato, `completed` quando tutti gli output sono completati e `failed` quando tutti gli output sono terminati e almeno uno non è riuscito. `completed` e `failed` sono stati terminali: il webhook `flows_template_run` viene attivato quando l'esecuzione raggiunge uno dei due.
  - Allowed values: `pending`, `generating`, `completed`, `failed`
- `outputs` (map from string to TemplateOutput, required) — Gli output dell'esecuzione, indicizzati in base all'ID della porta di output. Ciascuno è un `TemplateOutput` discriminato in base a `type`, il `type` del relativo `content_schema` della porta.

## Errors

### 422 Unprocessable Entity Error

Errore di convalida

- `detail` (list of ValidationError, optional)

## Types

### TemplateRunInput

Un valore associato a una porta di input del template, nel formato richiesto dal relativo `content_schema`. Una porta `string` accetta il testo stesso; le porte `number`, `integer` e `boolean` accettano un valore JSON del tipo corrispondente. Tutto ciò che è archiviato altrove è un riferimento distinto in base a `type`: una precedente `generation`, un `asset` caricato, una `voice` o un contenuto multimediale passato come `inline_base64`. Una porta `array` accetta un array JSON con un valore per elemento, ammesso dagli `items` dello schema. Le porte `object` non possono ancora essere associate tramite questa API. Qui non sono presenti vincoli oltre alla struttura wire: ciò che una porta accetta, ad esempio un `enum` o una lunghezza, è indicato dal relativo `content_schema`, mentre il percorso di esecuzione convalida rispetto allo stesso schema.

### WebhookTarget

- `type`: `all` (WebhookTargetAll)
- `type`: `ids` (WebhookTargetIds)
  - `ids` (list of string, required) — Gli ID dei webhook dei flow del workspace a cui inviare il risultato. Ciascuno deve essere uno dei webhook dei flow configurati nel workspace.

### TemplateOutput

Un output di un'esecuzione del template, distinto in base a `type`: il `type` del `content_schema` della porta. Controlla `status` per verificarne la fase del ciclo di vita.

- `type`: `array` (TemplateArrayOutput)
  - `has_more` (boolean, required) — Se l'elenco contiene elementi oltre `content`.
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (list of TemplateOutput, optional, nullable) — I primi elementi dell'elenco, in ordine, ciascuno conforme alla struttura di `items` dello schema. Presenti solo quando `status` è `completed`. Quando `has_more` è true, questo non è l'intero elenco. Riservato: nessun template produce ancora questo tipo di output; è pubblicato affinché i template che lo produrranno possano essere eseguiti con lo stesso client.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
  - `next_cursor` (string, optional, nullable) — Passa come `cursor` a un endpoint successivo per recuperare gli elementi dopo `content`. `null` quando `content` contiene l'intero elenco o prima del completamento dell'output. Riservato: nessun template produce ancora questo tipo di output; viene pubblicato affinché i template che lo producono possano essere eseguiti con lo stesso client.
- `type`: `audio` (TemplateAudioOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content_mime_type` (string, optional, nullable) — Il tipo MIME del file multimediale generato. Presente solo quando `status` è `completed`.
  - `content_url` (string, optional, nullable) — Un URL firmato da cui scaricare il contenuto multimediale generato. È presente solo quando `status` è `completed`. Scade circa un'ora dopo l'invio di questa risposta; recupera di nuovo l'esecuzione per ottenere un URL aggiornato.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `boolean` (TemplateBooleanOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (boolean, optional, nullable) — Il valore booleano generato. Presente solo quando `status` è `completed`. Riservato: nessun template produce ancora questo tipo di output; è pubblicato affinché i template che lo produrranno possano essere eseguiti con lo stesso client.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `image` (TemplateImageOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content_mime_type` (string, optional, nullable) — Il tipo MIME del file multimediale generato. Presente solo quando `status` è `completed`.
  - `content_url` (string, optional, nullable) — Un URL firmato da cui scaricare il contenuto multimediale generato. È presente solo quando `status` è `completed`. Scade circa un'ora dopo l'invio di questa risposta; recupera di nuovo l'esecuzione per ottenere un URL aggiornato.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `integer` (TemplateIntegerOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (integer, optional, nullable) — L'intero generato. Presente solo quando `status` è `completed`. Riservato: nessun template produce ancora questo tipo di output; è pubblicato affinché i template che lo produrranno possano essere eseguiti con lo stesso client.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `number` (TemplateNumberOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (double, optional, nullable) — Il numero generato. Presente solo quando `status` è `completed`. Riservato: nessun template produce ancora questo tipo di output; è pubblicato affinché i template che lo produrranno possano essere eseguiti con lo stesso client.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `object` (TemplateObjectOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (map from string to TemplateOutput, optional, nullable) — Un output per campo, identificato dal nome del campo, ciascuno conforme alla struttura dello schema del relativo campo. Presente solo quando `status` è `completed`. Riservato: nessun template produce ancora questo tipo di output; viene pubblicato affinché i template che lo producono possano essere eseguiti con lo stesso client.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `string` (TemplateStringOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (string, optional, nullable) — Il testo generato. Presente solo quando `status` è `completed`.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `video` (TemplateVideoOutput)
  - `id` (string, required) — L'ID della generazione associata a questo output. Passalo come riferimento `generation` per usare l'output come input altrove.
  - `status` (enum, required) — Lo stato del ciclo di vita dell'output. Termina con `completed`, quando sono impostati i campi del contenuto dell'output, oppure con `failed`, quando sono impostati `failure_reason` e `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content_mime_type` (string, optional, nullable) — Il tipo MIME del file multimediale generato. Presente solo quando `status` è `completed`.
  - `content_url` (string, optional, nullable) — Un URL firmato da cui scaricare il contenuto multimediale generato. È presente solo quando `status` è `completed`. Scade circa un'ora dopo l'invio di questa risposta; recupera di nuovo l'esecuzione per ottenere un URL aggiornato.
  - `error_message` (string, optional, nullable) — Una descrizione leggibile dell'errore. Presente solo quando `status` è `failed`. Le generazioni non riuscite non vengono addebitate.
  - `failure_reason` (enum, optional, nullable) — La categoria dell'errore. Presente solo quando `status` è `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### ValidationErrorLocItems

## Examples

**Request**

```json
{
  "inputs": {
    "prompt": "a corgi on a surfboard",
    "reference": {
      "asset_id": "5xM2KqOnZyce22SPZ9d4",
      "type": "asset"
    }
  },
  "version_id": "latest",
  "webhook": {
    "type": "all"
  }
}
```

**Response**

```json
{
  "id": "sess_JWr5N6X9ZTqf8jD2LmQb",
  "template_id": "tmpl_abc123",
  "version_id": "ver_01hxyz",
  "status": "generating",
  "outputs": {
    "marketing_title": {
      "type": "string",
      "id": "Kx2mP7Y4WVrg9kE3NnRc",
      "status": "completed",
      "content": "Ride the wave."
    },
    "product_demo": {
      "type": "video",
      "id": "QWr5N6X9ZTqf8jD2La3B",
      "status": "generating"
    },
    "product_still": {
      "type": "image",
      "id": "JWr5N6X9ZTqf8jD2LmQb",
      "status": "completed",
      "content_mime_type": "image/png",
      "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/flows/templates/template_id/runs"

payload = {
    "inputs": {
        "prompt": "a corgi on a surfboard",
        "reference": {
            "asset_id": "5xM2KqOnZyce22SPZ9d4",
            "type": "asset"
        }
    },
    "version_id": "latest",
    "webhook": { "type": "all" }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/flows/templates/template_id/runs';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"inputs":{"prompt":"a corgi on a surfboard","reference":{"asset_id":"5xM2KqOnZyce22SPZ9d4","type":"asset"}},"version_id":"latest","webhook":{"type":"all"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/flows/templates/template_id/runs"

	payload := strings.NewReader("{\n  \"inputs\": {\n    \"prompt\": \"a corgi on a surfboard\",\n    \"reference\": {\n      \"asset_id\": \"5xM2KqOnZyce22SPZ9d4\",\n      \"type\": \"asset\"\n    }\n  },\n  \"version_id\": \"latest\",\n  \"webhook\": {\n    \"type\": \"all\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/flows/templates/template_id/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": {\n    \"prompt\": \"a corgi on a surfboard\",\n    \"reference\": {\n      \"asset_id\": \"5xM2KqOnZyce22SPZ9d4\",\n      \"type\": \"asset\"\n    }\n  },\n  \"version_id\": \"latest\",\n  \"webhook\": {\n    \"type\": \"all\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/flows/templates/template_id/runs")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {\n    \"prompt\": \"a corgi on a surfboard\",\n    \"reference\": {\n      \"asset_id\": \"5xM2KqOnZyce22SPZ9d4\",\n      \"type\": \"asset\"\n    }\n  },\n  \"version_id\": \"latest\",\n  \"webhook\": {\n    \"type\": \"all\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/flows/templates/template_id/runs', [
  'body' => '{
  "inputs": {
    "prompt": "a corgi on a surfboard",
    "reference": {
      "asset_id": "5xM2KqOnZyce22SPZ9d4",
      "type": "asset"
    }
  },
  "version_id": "latest",
  "webhook": {
    "type": "all"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/flows/templates/template_id/runs");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"inputs\": {\n    \"prompt\": \"a corgi on a surfboard\",\n    \"reference\": {\n      \"asset_id\": \"5xM2KqOnZyce22SPZ9d4\",\n      \"type\": \"asset\"\n    }\n  },\n  \"version_id\": \"latest\",\n  \"webhook\": {\n    \"type\": \"all\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "inputs": [
    "prompt": "a corgi on a surfboard",
    "reference": [
      "asset_id": "5xM2KqOnZyce22SPZ9d4",
      "type": "asset"
    ]
  ],
  "version_id": "latest",
  "webhook": ["type": "all"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/flows/templates/template_id/runs")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```