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

# Crear ejecución de plantilla

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

Inicia una ejecución de una plantilla de flows. Pasa `version_id` para fijar una instantánea, u omítelo/pasa `latest` para ejecutar la última versión publicada. Define los valores de entrada en `inputs`, indexados por el ID del puerto de entrada. La respuesta es la ejecución en su estado inicial, con cada salida ya incluida bajo su ID de puerto en `outputs`. Incluye `webhook` para recibir un evento `flows_template_run` con la ejecución finalizada cuando su `status` sea `completed` o `failed`; esta es la forma recomendada de esperar. Sin uno, consulta `GET /v1/flows/templates/{template_id}/runs/{run_id}` a intervalos moderados hasta que el `status` sea terminal.

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) — El ID de la plantilla, tal como se muestra en la app de ElevenLabs o mediante `GET /v1/flows/templates`.

### Body (application/json)

This endpoint expects a TemplateRunCreateRequest.

- `inputs` (map from string to TemplateRunInput, required) — Valores de entrada identificados mediante el ID del puerto de entrada. Debes proporcionar todos los puertos de entrada de la versión que se ejecuta; se rechaza un ID ausente o desconocido. Pasa `{}` para una plantilla sin entradas.
- `version_id` (string, optional, nullable) — La instantánea de plantilla que se va a ejecutar. Proporciona un ID de versión específico para fijar esa instantánea o `latest` (el valor predeterminado si se omite) para ejecutar la versión publicada más recientemente de la plantilla. Solo se pueden fijar versiones publicadas, excepto el propietario de la plantilla, que también puede fijar una instantánea guardada no publicada para probarla antes de publicarla. El borrador activo nunca se ejecuta mediante esta API.
- `webhook` (WebhookTarget, optional, nullable) — Inclúyelo para enviar el resultado de la ejecución a los webhooks de flows configurados en el espacio de trabajo cuando el `status` de la ejecución alcance `completed` o `failed`. Un evento para toda la ejecución: los `data` del evento `flows_template_run` coinciden con la respuesta final de `GET /v1/flows/templates/{template_id}/runs/{run_id}`.

## Response

### 200

Respuesta correcta.

- `id` (string, required) — El identificador único de la ejecución.
- `template_id` (string, required) — La plantilla que ejecutó esta ejecución, para que un consumidor de webhook que ejecute varias plantillas pueda distinguir sus ejecuciones sin mantener una asignación entre ejecuciones y plantillas.
- `version_id` (string, required) — La versión de la plantilla que ejecutó esta ejecución. Se resuelve al crear la ejecución, por lo que una ejecución iniciada con `latest` registra la versión concreta que ejecutó.
- `status` (enum, required) — El estado de la ejecución, calculado a partir de sus resultados: `pending` hasta que se inicie un resultado, `generating` mientras haya algún resultado sin finalizar, `completed` cuando todos los resultados se hayan completado y `failed` cuando todos hayan terminado y al menos uno haya fallado. `completed` y `failed` son estados finales: el webhook `flows_template_run` se activa cuando la ejecución alcanza cualquiera de ellos.
  - Allowed values: `pending`, `generating`, `completed`, `failed`
- `outputs` (map from string to TemplateOutput, required) — Los resultados de la ejecución, indexados por ID de puerto de salida. Cada uno es un `TemplateOutput` discriminado por `type`, el `type` de `content_schema` de su puerto.

## Errors

### 422 Unprocessable Entity Error

Error de validación

- `detail` (list of ValidationError, optional)

## Types

### TemplateRunInput

Un valor vinculado a un puerto de entrada de plantilla, en el formato que requiere su `content_schema`. Un puerto `string` recibe el propio texto; los puertos `number`, `integer` y `boolean` reciben un valor JSON de ese tipo. Todo lo almacenado en otro lugar es una referencia diferenciada por `type`: una `generation` anterior, un `asset` cargado, una `voice` o contenido multimedia pasado mediante `inline_base64`. Un puerto `array` recibe una matriz JSON con un valor por elemento, admisible para los `items` del esquema. Los puertos `object` aún no pueden vincularse mediante esta API. Aquí no se definen restricciones más allá de la estructura de transmisión: lo que acepta un puerto (un `enum`, una longitud) se indica en su `content_schema`, y la ruta de ejecución valida con ese mismo esquema.

### WebhookTarget

- `type`: `all` (WebhookTargetAll)
- `type`: `ids` (WebhookTargetIds)
  - `ids` (list of string, required) — Los ID de los webhooks de flujos del espacio de trabajo a los que se enviará el resultado. Cada uno debe ser uno de los webhooks de flujos configurados en el espacio de trabajo.

### TemplateOutput

Una salida de una ejecución de plantilla, diferenciada por `type`: el `type` del `content_schema` del puerto. Consulta `status` para saber en qué punto de su ciclo de vida se encuentra.

- `type`: `array` (TemplateArrayOutput)
  - `has_more` (boolean, required) — Indica si la lista tiene elementos además de `content`.
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (list of TemplateOutput, optional, nullable) — Los primeros elementos de la lista, en orden, cada uno con la forma definida por `items` en el esquema. Solo está presente cuando `status` es `completed`. Cuando `has_more` es true, no se trata de la lista completa. Reservado: ninguna plantilla produce aún este tipo de salida; se publica para que las plantillas que lo hagan puedan ejecutarse con el mismo cliente.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
  - `next_cursor` (string, optional, nullable) — Pásalo como `cursor` a una ruta de API posterior para obtener los elementos que siguen a `content`. `null` cuando `content` contiene la lista completa o antes de que se complete la salida. Reservado: todavía no hay ninguna plantilla que produzca este tipo de salida; se publica para que las plantillas que sí lo hagan puedan ejecutarse con el mismo cliente.
- `type`: `audio` (TemplateAudioOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content_mime_type` (string, optional, nullable) — El tipo MIME del contenido multimedia generado. Solo está presente cuando `status` es `completed`.
  - `content_url` (string, optional, nullable) — Una URL firmada desde la que descargar el contenido multimedia generado. Solo está presente cuando `status` es `completed`. Caduca aproximadamente una hora después de que se devuelva esta respuesta; vuelve a consultar la ejecución para obtener una URL nueva.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `boolean` (TemplateBooleanOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (boolean, optional, nullable) — El valor booleano generado. Solo está presente cuando `status` es `completed`. Reservado: ninguna plantilla produce aún este tipo de salida; se publica para que las plantillas que lo hagan puedan ejecutarse con el mismo cliente.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `image` (TemplateImageOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content_mime_type` (string, optional, nullable) — El tipo MIME del contenido multimedia generado. Solo está presente cuando `status` es `completed`.
  - `content_url` (string, optional, nullable) — Una URL firmada desde la que descargar el contenido multimedia generado. Solo está presente cuando `status` es `completed`. Caduca aproximadamente una hora después de que se devuelva esta respuesta; vuelve a consultar la ejecución para obtener una URL nueva.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `integer` (TemplateIntegerOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (integer, optional, nullable) — El número entero generado. Solo está presente cuando `status` es `completed`. Reservado: ninguna plantilla produce aún este tipo de salida; se publica para que las plantillas que lo hagan puedan ejecutarse con el mismo cliente.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `number` (TemplateNumberOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (double, optional, nullable) — El número generado. Solo está presente cuando `status` es `completed`. Reservado: ninguna plantilla produce aún este tipo de salida; se publica para que las plantillas que lo hagan puedan ejecutarse con el mismo cliente.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `object` (TemplateObjectOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (map from string to TemplateOutput, optional, nullable) — Una salida por campo, identificada por el nombre del campo y siguiendo cada una la estructura del esquema de ese campo. Solo está presente cuando `status` es `completed`. Reservado: ninguna plantilla genera aún este tipo de salida; se publica para que las plantillas que lo hagan puedan ejecutarse con el mismo cliente.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `string` (TemplateStringOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content` (string, optional, nullable) — El texto generado. Solo está presente cuando `status` es `completed`.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `failed`.
    - Allowed values: `timeout`, `model_error`, `moderated`, `invalid_parameters`, `dependency_failed`, `charging_failed`, `internal_error`
- `type`: `video` (TemplateVideoOutput)
  - `id` (string, required) — El ID de la generación detrás de esta salida. Pásalo como referencia `generation` para usar la salida como entrada en otro lugar.
  - `status` (enum, required) — El estado del ciclo de vida de la salida. Finaliza en `completed`, cuando se establecen los campos de contenido de la salida, o en `failed`, cuando se establecen `failure_reason` y `error_message`.
    - Allowed values: `pending`, `generating`, `completed`, `failed`
  - `content_mime_type` (string, optional, nullable) — El tipo MIME del contenido multimedia generado. Solo está presente cuando `status` es `completed`.
  - `content_url` (string, optional, nullable) — Una URL firmada desde la que descargar el contenido multimedia generado. Solo está presente cuando `status` es `completed`. Caduca aproximadamente una hora después de que se devuelva esta respuesta; vuelve a consultar la ejecución para obtener una URL nueva.
  - `error_message` (string, optional, nullable) — Una descripción legible del error. Solo está presente cuando `status` es `failed`. Las generaciones fallidas no se cobran.
  - `failure_reason` (enum, optional, nullable) — La categoría del fallo. Solo está presente cuando `status` es `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()
```