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

# Guía de inicio rápido de Imagen y Video

La API de Imagen y Video es asíncrona. Envías una generación y, cuando termina, descargas el resultado desde una URL firmada. Las imágenes y los vídeos tienen rutas de API independientes, pero las estructuras de solicitud y respuesta son las mismas para ambos.

Hay dos formas de obtener el resultado. La [entrega mediante webhook](/docs/es/eleven-api/guides/how-to/image-and-video/webhooks) es la recomendada y la que usan los ejemplos siguientes: ElevenLabs llama a tu ruta de API en cuanto una generación alcanza un estado final, por lo que no se pierde tiempo esperando. El sondeo es la alternativa si no tienes una ruta de API para recibir una devolución de llamada, y cada ejemplo muestra cómo recurrir a él.

> **Warning**
>
> La API de Imagen y Video requiere un plan Pro o superior. Las llamadas desde un espacio de trabajo de un nivel inferior
> se rechazan con un error `402 paid_plan_required`. Tu clave de API también debe tener el permiso de Imagen y Video o
> Flows para el espacio de trabajo.

## Genera una imagen

#### Crea una clave de API

[Crea una clave de API en el panel aquí](https://elevenlabs.io/app/settings/api-keys), que usarás para [acceder a la API](/docs/es/api-reference/authentication) de forma segura.

Guarda la clave como un secreto gestionado y pásala a los SDK como variable de entorno mediante un archivo `.env` o directamente en la configuración de tu aplicación, según prefieras.

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### Instala el SDK

#### SDK

También usaremos la biblioteca `dotenv` para cargar nuestra clave de API desde una variable de entorno.

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

Instala la CLI de ElevenLabs. Recomendamos Homebrew (macOS) y Scoop (Windows).

**`Homebrew (macOS)`**

```bash title="Homebrew (macOS)"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop (Windows)`**

```powershell title="Scoop (Windows)"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> ¿Trabajas con un asistente de programación con IA? Ejecuta `elevenlabs generate-skills` en tu proyecto para crear un
> `SKILL.md` para cada grupo de comandos en `skills/`, para que tu asistente conozca todas las funciones de la CLI
> sin que tengas que pegar la documentación. Usa `--output-dir` para guardarlos en otro lugar. Esto lee la definición de la API
> integrada en la propia CLI, por lo que no necesita una clave de API y funciona sin conexión; además, se mantiene al día con
> la versión de la CLI que tengas instalada.

Después, autentícate; se abrirá el navegador para autorizar la CLI:

```bash
elevenlabs auth login
```

#### Envía la generación

Cada modelo tiene su propia clase de solicitud, y sus campos son los parámetros que acepta ese
modelo, por lo que al cambiar de modelo pueden cambiar los campos disponibles. Los campos desconocidos se rechazan
en lugar de ignorarse.

`webhook` solicita que el resultado terminado se entregue a los webhooks de tu espacio de trabajo, por lo que la llamada
devuelve el control en cuanto la generación se pone en cola. Requiere un webhook suscrito a eventos de generación;
consulta [webhooks de Imagen y Video](/docs/es/eleven-api/guides/how-to/image-and-video/webhooks) para configurarlo u omite el
campo y usa el sondeo en su lugar.

#### SDK

```python
# example.py
import os

from dotenv import load_dotenv
from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
        aspect_ratio="16:9",
        resolution="2K",
        webhook=WebhookTarget_All(),
    )
)

print(generation.id, generation.status)
```

```typescript
// example.mts
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

const generation = await elevenlabs.flows.image.create({
  modelId: "gemini-3-pro-image",
  prompt:
    "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
  aspectRatio: "16:9",
  resolution: "2K",
  webhook: { type: "all" },
});

console.log(generation.id, generation.status);
```

#### CLI

La CLI envía la misma solicitud como JSON, después sondea hasta que la generación se completa y descarga el resultado:

```bash
# 1. Submit the generation (note the returned id)
elevenlabs flows image create --json '{
  "model_id": "gemini-3-pro-image",
  "prompt": "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

# 2. Poll until the status is "completed"
elevenlabs flows image get --generation-id <id> --query status

# 3. Read the signed content URL, then download the image
elevenlabs flows image get --generation-id <id> --query content_url
curl -o corgi.png "<content_url>"
```

La respuesta contiene el ID de la generación y nada más. Una generación recién creada siempre está
`pending`:

```json
{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}
```

#### Obtén el resultado

Como la solicitud incluía `webhook`, ElevenLabs envía un evento `flows_generation` a tu
ruta de API cuando la generación alcanza `completed` o `failed`. Los `data` del evento son idénticos a
los que devuelve la ruta de API GET, y los [webhooks de Imagen y Video](/docs/es/eleven-api/guides/how-to/image-and-video/webhooks) explican
cómo implementar el controlador que lo recibe.

Si no tienes una ruta de API para recibir devoluciones de llamada, elimina `webhook` de la solicitud anterior y usa el sondeo.
Obtén la generación hasta que su estado sea `completed` o `failed`, dejando al menos dos segundos
entre solicitudes para una imagen; consulta las [pautas de sondeo](#polling-guidelines) para conocer los intervalos
que debes usar para cada modalidad.

```python maxLines=0
import time

import requests

while True:
    result = elevenlabs.flows.image.get(generation.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(2)

if result.status == "failed":
    raise RuntimeError(f"{result.failure_reason}: {result.error_message}")

with open("corgi.png", "wb") as f:
    f.write(requests.get(result.content_url).content)
```

```typescript maxLines=0
import { writeFile } from "fs/promises";

let result = await elevenlabs.flows.image.get(generation.id);

while (result.status === "pending" || result.status === "generating") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  result = await elevenlabs.flows.image.get(generation.id);
}

if (result.status === "failed") {
  throw new Error(`${result.failureReason}: ${result.errorMessage}`);
}

const response = await fetch(result.contentUrl);
await writeFile("corgi.png", Buffer.from(await response.arrayBuffer()));
```

En ambos casos, una generación completada incluye los mismos campos:

```json
{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}
```

#### Ejecuta el código

```python
python example.py
```

```typescript
npx tsx example.mts
```

La generación se pone en cola y se muestra su ID. Con entrega mediante webhook, la imagen llega a tu
ruta de API; con la variante de sondeo, se guarda en `corgi.png`.

## Genera un vídeo

Las generaciones de vídeo usan `flows.video` y siguen el mismo patrón de envío y recogida. Un vídeo puede tardar
varios minutos, así que este ejemplo usa la entrega mediante webhook con `webhook` en lugar de esperar
el resultado.

```python
from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All

generation = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
        duration_secs=8,
        aspect_ratio="16:9",
        resolution="1080p",
        generate_audio=True,
        webhook=WebhookTarget_All(),
    )
)

print(generation.id)
```

```typescript
const generation = await elevenlabs.flows.video.create({
  modelId: "veo-3.1-fast-generate-001",
  prompt: "A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
  durationSecs: 8,
  aspectRatio: "16:9",
  resolution: "1080p",
  generateAudio: true,
  webhook: { type: "all" },
});

console.log(generation.id);
```

La llamada devuelve el control en cuanto la generación se pone en cola, y el resultado terminado se entrega a todos los
webhooks de tu espacio de trabajo suscritos a eventos de generación. La salida de vídeo es MP4, por lo que la carga completada informa de un
`content_mime_type` de `video/mp4`. Consulta los
[webhooks de Imagen y Video](/docs/es/eleven-api/guides/how-to/image-and-video/webhooks) para configurar un
webhook e implementar el controlador que recibe este evento.

> **Warning**
>
> `webhook` requiere al menos un webhook del espacio de trabajo suscrito a eventos de generación. Sin uno,
> la llamada de creación se rechaza en lugar de iniciar una generación cuyo resultado no tiene adónde ir. Elimina
> el campo para usar el sondeo con `flows.video.get` y no sondees más de una vez cada 10
> segundos.

## Recopilar resultados

Los webhooks y el polling devuelven la misma carga útil, así que la elección depende de cómo esperas a recibirla, no de
lo que recibes.

|                 | Entrega mediante webhook                                     | Polling                                        |
| --------------- | ------------------------------------------------------------ | ---------------------------------------------- |
| Ideal para      | La opción predeterminada para ambas modalidades y producción | Scripts y entornos sin una ruta de API pública |
| Requiere        | Una ruta de API HTTPS suscrita a eventos de generación       | Nada                                           |
| Coste de espera | Ninguno; te llamamos cuando termina la generación            | Una solicitud por sondeo y generación          |

Usa webhooks siempre que puedas. Recurre al polling cuando no tengas dónde recibir una devolución de llamada y,
cuando lo hagas, sigue los intervalos que indicamos a continuación.

### Elegir destinos de webhook

`webhook` acepta dos formatos. `WebhookTarget_All` llega a todos los webhooks suscritos a eventos de generación,
que es la opción predeterminada adecuada porque sigue funcionando aunque los webhooks se roten o sustituyan.
`WebhookTarget_Ids` limita la entrega a webhooks específicos, para cuando un espacio de trabajo distribuye a varios
consumidores y un trabajo concreto solo debe llegar a uno de ellos:

```python
from elevenlabs import WebhookTarget_Ids

webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])
```

```typescript
const webhook = { type: "ids", ids: ["Q8mVr2LpXcT4nB6yJdKw"] };
```

Todos los ID ya deben estar suscritos a eventos de generación; indicar un webhook no suscrito se
rechaza en lugar de ignorarse sin aviso. La carga útil entregada es idéntica a la que devuelve la ruta de API GET,
así que un controlador creado para uno sirve para el otro. La
[guía sobre webhooks](/docs/es/eleven-api/guides/how-to/image-and-video/webhooks) explica cómo configurar un
webhook, verificar la firma y gestionar el evento.

### Pautas para el polling

El tiempo de ejecución de una generación depende del modelo, la resolución y, en el caso del vídeo, la duración, así que haz polling
a un intervalo adaptado a lo que has solicitado, en lugar de hacerlo en un bucle fijo:

* **Imágenes**: no hagas polling más de una vez cada 2 segundos. La mayoría terminan en unos segundos.
* **Vídeo**: no hagas polling más de una vez cada 10 segundos. Espera minutos, no segundos, y ajusta el
  intervalo según `duration_secs` y `resolution`.

Hay dos reglas para ambos casos. Aumenta el intervalo si una generación tarda mucho — duplicarlo hasta aproximadamente un
minuto evita que una generación lenta se convierta en cientos de solicitudes. Y establece un límite para el bucle,
para que una generación bloqueada termine como un tiempo de espera en tu propio código en lugar de como un bucle ilimitado.

Hacer polling más rápido no aporta nada: el estado de una generación no cambia antes porque
lo hayas consultado dos veces. Un polling agresivo y continuado puede devolver
[respuestas 429](/docs/es/eleven-api/resources/errors#rate-limiting-and-concurrency), que debes
gestionar con una espera exponencial.

## Ciclo de vida de una generación

Una generación pasa por cuatro estados. Los dos estados finales contienen campos distintos, así que
depende de `status` antes de leer el resto de la respuesta.

| Estado       | Significado                                                                              |
| ------------ | ---------------------------------------------------------------------------------------- |
| `pending`    | La generación está en cola. Es el estado de todas las generaciones recién creadas.       |
| `generating` | El modelo se está ejecutando.                                                            |
| `completed`  | El resultado está listo. La respuesta contiene `content_url` y `content_mime_type`.      |
| `failed`     | La generación no produjo ningún resultado. La respuesta contiene los detalles del error. |

> **Warning**
>
> `content_url` es una URL firmada que caduca aproximadamente una hora después de devolver la respuesta. Obtén
> la generación de nuevo para conseguir una URL actualizada, en lugar de guardar la propia URL firmada.

## Gestionar errores

Una generación fallida informa de una categoría `failure_reason` junto con un `error_message` legible para las personas:

```json
{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}
```

| `failure_reason`     | Causa                                                                    |
| -------------------- | ------------------------------------------------------------------------ |
| `timeout`            | El modelo no devolvió un resultado a tiempo.                             |
| `model_error`        | El proveedor del modelo devolvió un error o no produjo ningún resultado. |
| `moderated`          | El prompt o una entrada fue rechazado por la moderación de contenido.    |
| `invalid_parameters` | Los parámetros se rechazaron cuando la generación llegó al modelo.       |
| `dependency_failed`  | Falló una generación de la que depende esta.                             |
| `charging_failed`    | No se pudo cobrar la generación al espacio de trabajo.                   |
| `internal_error`     | Se produjo un error inesperado.                                          |

Las generaciones fallidas no se cobran. Los problemas de parámetros que pueden detectarse de antemano — un
campo no compatible, un valor fuera del rango permitido de un modelo o una combinación no válida de entradas de
referencia — se rechazan en la solicitud de creación antes de que comience ninguna generación.

## Precios

Las generaciones se cobran en créditos. El coste depende del modelo, de los parámetros que elijas, como la
resolución y la duración, y de las entradas que proporciones. Una generación cuesta lo mismo mediante la API que
en la app de ElevenLabs, donde se muestra el coste antes de enviarla. Consulta
[Imagen y Video en el playground](/docs/es/eleven-creative/playground/image-video) para saber cómo se presenta el coste de
una combinación concreta de modelo y ajustes.

## Consulta tus generaciones

Cada ruta de API enumera las generaciones creadas a través de ella, empezando por las más recientes. Los resultados se limitan a tu
espacio de trabajo y a esta API, por lo que las generaciones creadas en la app de ElevenLabs no aparecen.

```python
page = elevenlabs.flows.image.list(page_size=20, status="completed")

for item in page.generations:
    print(item.id, item.content_url)

while page.has_more:
    page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor)
    for item in page.generations:
        print(item.id, item.content_url)
```

```typescript
let page = await elevenlabs.flows.image.list({ pageSize: 20, status: "completed" });

for (const item of page.generations) {
  console.log(item.id, item.contentUrl);
}

while (page.hasMore) {
  page = await elevenlabs.flows.image.list({
    pageSize: 20,
    status: "completed",
    cursor: page.nextCursor,
  });
  for (const item of page.generations) {
    console.log(item.id, item.contentUrl);
  }
}
```

`page_size` acepta valores de 1 a 100 y el valor predeterminado es 30. Pasa `status` para devolver solo las generaciones en un
estado del ciclo de vida y `model_id` para devolver solo las generaciones de un único modelo. Trata `next_cursor` como
un valor opaco: devuelve el valor exacto y detente cuando `has_more` sea `false`.

## Modelos disponibles

La API expone un subconjunto de los modelos disponibles en la app de ElevenLabs. Cada modelo acepta solo los
parámetros indicados para él; enviar un campo compatible con otro modelo devuelve un error de validación.

> **Warning**
>
> Los modelos de ByteDance están desactivados de forma predeterminada y requieren aprobación explícita antes de usarlos. Hasta que se
> conceda el acceso, se rechazará una solicitud que indique uno de ellos con un error `model_access_denied`. Los clientes Enterprise
> pueden contactar con soporte para solicitar acceso.

### Modelos de imagen

| `model_id`                    | Imágenes de referencia   | Controles de salida                                                          |
| ----------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| `gpt-image-1`                 | Hasta 5, más una `mask`  | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background`                      |
| `gpt-image-1.5`               | Hasta 5, más una `mask`  | `aspect_ratio` (1:1, 3:2, 2:3), `quality`, `background`                      |
| `gpt-image-2`                 | Hasta 10, más una `mask` | 15 relaciones de aspecto, `resolution` (1K, 2K, 4K), `quality`               |
| `gpt-image-2.5-sunburst`      | Hasta 10, más una `mask` | 15 relaciones de aspecto, `resolution` (1K, 2K, 4K), `quality` (hasta `max`) |
| `gpt-image-2.5-flare`         | Hasta 10, más una `mask` | 15 relaciones de aspecto, `resolution` (1K, 2K, 4K), `quality` (hasta `max`) |
| `gemini-2.5-flash-image`      | Hasta 5                  | `aspect_ratio`                                                               |
| `gemini-3-pro-image`          | Hasta 10                 | `aspect_ratio`, `resolution` (1K, 2K, 4K)                                    |
| `gemini-3.1-flash-image`      | Hasta 14                 | `aspect_ratio` (incluidas 1:4, 4:1, 1:8, 8:1), `resolution` (de 512 a 4K)    |
| `gemini-3.1-flash-lite-image` | Hasta 14                 | `aspect_ratio`, `resolution` (1K)                                            |
| `bytedance-seedream-5-lite`   | Hasta 10                 | `aspect_ratio`, `resolution` (2K, 3K), `seed`                                |
| `bytedance-seedream-5-pro`    | Hasta 10                 | `aspect_ratio`, `resolution` (1K, 2K), `seed`                                |

Los modelos GPT Image 2.5 aceptan los valores `low`, `medium`, `high`, `xhigh` y `max` para `quality`, y el valor
predeterminado es `high`. GPT Image 2 llega hasta `high` y el valor predeterminado es `medium`.

### Modelos de vídeo

| `model_id`                   | Entradas multimedia                                                     | Controles de salida                                                                                      |
| ---------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `veo-3.1-generate-001`       | `start_frame`, `end_frame`, hasta 3 `images` con un `role`              | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` |
| `veo-3.1-fast-generate-001`  | `start_frame`, `end_frame`, hasta 3 `images` con un `role`              | `duration_secs` (4, 6, 8), `aspect_ratio` (16:9, 9:16), `resolution` (720p, 1080p, 4K), `generate_audio` |
| `bytedance-seedance-v2`      | `start_frame`, `end_frame`, hasta 9 `images`, 3 `videos`, 3 `audios`    | `duration_secs` (de 4 a 15), 7 relaciones de aspecto, `resolution` (de 480p a 4k), `generate_audio`      |
| `bytedance-seedance-v2-fast` | `start_frame`, `end_frame`, hasta 9 `images`, 3 `videos`, 3 `audios`    | `duration_secs` (de 4 a 15), 7 relaciones de aspecto, `resolution` (480p, 720p), `generate_audio`        |
| `bytedance-seedance-v2-mini` | `start_frame`, `end_frame`, hasta 9 `images`, 3 `videos`, 3 `audios`    | `duration_secs` (de 4 a 15), 7 relaciones de aspecto, `resolution` (480p, 720p), `generate_audio`        |
| `bytedance-seedance-v2.5`    | `start_frame`, `end_frame`, hasta 30 `images`, 10 `videos`, 10 `audios` | `duration_secs` (de 4 a 30), 7 relaciones de aspecto, `resolution` (480p, 720p), `generate_audio`        |
| `creatify-aurora`            | `image` y `audio`, ambos obligatorios                                   | `resolution` (480p, 720p), `guidance_scale`, `audio_guidance_scale`                                      |

Para consultar las capacidades, la disponibilidad y los precios de los modelos, consulta la
[visión general de Imagen y Video](/docs/es/overview/capabilities/image-video).

## Próximos pasos

#### [Referencias y recursos](/docs/es/eleven-api/guides/how-to/image-and-video/references)

Guía una generación con una generación anterior, un recurso subido o contenido multimedia en línea.

#### [Webhooks](/docs/es/eleven-api/guides/how-to/image-and-video/webhooks)

Recibe el resultado de una generación en lugar de hacer polling.

#### [Referencia de la API](/docs/es/api-reference/flows/image/create)

Explora las rutas de API de imagen, vídeo y recursos.