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

# Generación de Video SkyReels V4

>  - Dos niveles de modelo: Fast (optimizado para velocidad) y Std (optimizado para calidad)
- Tres modos enrutados automáticamente según los campos de la solicitud: Text-to-Video (T2V), Image-to-Video (I2V), Referencia multimodal (Omni)
- Resolución 480p / 720p / 1080p, duración de 3 a 15 segundos
- Funciones avanzadas: primer/último/fotograma clave, imágenes de referencia, videos de referencia, collage en cuadrícula, extensión de video, sincronización de audio
- Modo de procesamiento asíncrono, devuelve un ID de tarea para consultas posteriores 

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "skyreels-v4-fast",
    "prompt": "A serene forest at sunset with golden light filtering through the trees.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "prompt_optimizer": true
  }'
```

```python Python theme={null}
import requests

url = "https://gccai.heqingsong.uk/v1/videos/generations"

payload = {
    "model": "skyreels-v4-fast",
    "prompt": "A serene forest at sunset with golden light filtering through the trees.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "prompt_optimizer": True
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://gccai.heqingsong.uk/v1/videos/generations";

const payload = {
  model: "skyreels-v4-fast",
  prompt: "A serene forest at sunset with golden light filtering through the trees.",
  duration: 5,
  resolution: "1080p",
  aspect_ratio: "16:9",
  prompt_optimizer: true
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://gccai.heqingsong.uk/v1/videos/generations"

    payload := map[string]interface{}{
        "model":            "skyreels-v4-fast",
        "prompt":           "A serene forest at sunset with golden light filtering through the trees.",
        "duration":         5,
        "resolution":       "1080p",
        "aspect_ratio":     "16:9",
        "prompt_optimizer": true,
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={null}
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://gccai.heqingsong.uk/v1/videos/generations";

        String payload = """
        {
          "model": "skyreels-v4-fast",
          "prompt": "A serene forest at sunset with golden light filtering through the trees.",
          "duration": 5,
          "resolution": "1080p",
          "aspect_ratio": "16:9",
          "prompt_optimizer": true
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer <token>")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
```

```php PHP theme={null}
<?php

$url = "https://gccai.heqingsong.uk/v1/videos/generations";

$payload = [
    "model" => "skyreels-v4-fast",
    "prompt" => "A serene forest at sunset with golden light filtering through the trees.",
    "duration" => 5,
    "resolution" => "1080p",
    "aspect_ratio" => "16:9",
    "prompt_optimizer" => true
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
```

```ruby Ruby theme={null}
require 'net/http'
require 'json'
require 'uri'

url = URI("https://gccai.heqingsong.uk/v1/videos/generations")

payload = {
  model: "skyreels-v4-fast",
  prompt: "A serene forest at sunset with golden light filtering through the trees.",
  duration: 5,
  resolution: "1080p",
  aspect_ratio: "16:9",
  prompt_optimizer: true
}

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = payload.to_json

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

```swift Swift theme={null}
import Foundation

let url = URL(string: "https://gccai.heqingsong.uk/v1/videos/generations")!

let payload: [String: Any] = [
    "model": "skyreels-v4-fast",
    "prompt": "A serene forest at sunset with golden light filtering through the trees.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "prompt_optimizer": true
]

var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error: \(error)")
        return
    }

    if let data = data, let responseString = String(data: data, encoding: .utf8) {
        print(responseString)
    }
}

task.resume()
```

```csharp C# theme={null}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://gccai.heqingsong.uk/v1/videos/generations";

        var payload = @"{
            ""model"": ""skyreels-v4-fast"",
            ""prompt"": ""A serene forest at sunset with golden light filtering through the trees."",
            ""duration"": 5,
            ""resolution"": ""1080p"",
            ""aspect_ratio"": ""16:9"",
            ""prompt_optimizer"": true
        }";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");

        var content = new StringContent(payload, Encoding.UTF8, "application/json");
        var response = await client.PostAsync(url, content);
        var result = await response.Content.ReadAsStringAsync();

        Console.WriteLine(result);
    }
}
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPEY5H3NQ2W8D7T6VB3F9GR4"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Insufficient account balance, please top up and try again",
    "type": "payment_required"
  }
}
```

```json 422 theme={null}
{
  "error": {
    "code": 422,
    "message": "Parameter conflict or invalid value (e.g. I2V and Omni fields passed simultaneously)",
    "type": "invalid_request_error"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "Internal server error, please retry later",
    "type": "server_error"
  }
}
```

## Autorización

**Authorization** `string` *required*

Todos los endpoints de la API requieren autenticación mediante Bearer Token

Obtenga su API Key:

Visite la [página de gestión de API Keys](https://gccai.heqingsong.uk/keys) para obtener su API Key

Añádala al encabezado de la solicitud:

```
Authorization: Bearer YOUR_API_KEY
```

## Modos de generación

SkyReels V4 se enruta automáticamente al modo correcto según los campos de la solicitud — **no se necesita el campo `mode`**:

| Modo | Activador | Capacidad |
| - | - | - |
| **T2V** (Text-to-Video) | Solo `prompt` + campos generales | Generación basada únicamente en texto |
| **I2V** (Image-to-Video) | Cualquiera de `first_frame_image` / `end_frame_image` / `mid_frame_images` | Control de primer/último/fotograma clave |
| **Omni** (Referencia multimodal) | Cualquiera de `ref_images` / `ref_videos` | Referencia de sujeto, collage en cuadrícula, referencia de movimiento, extensión de video, sincronización de audio |

> [!WARNING]
>
> **Exclusión mutua estricta**: los campos I2V (`first_frame_image` / `end_frame_image` / `mid_frame_images`) y los campos Omni (`ref_images` / `ref_videos`) no pueden usarse juntos; de lo contrario, se devuelve 422.

> [!NOTE]
>
> **Mecanismo `@tag`**: Al usar `mid_frame_images` / `ref_images` / `ref_videos`, cada elemento debe declarar un `tag` que comience con `@` (por ejemplo, `@image1`, `@Actor-1`, `@video1`), y el `tag` **debe aparecer en el `prompt`**.
>
> Piense en el `prompt` como un "guion" y en el `tag` como un "puntero de personaje" hacia activos específicos (imágenes / videos). Por ejemplo, un prompt como `"@Actor-1 walks into the scene of @video1"` indica al sistema que inyecte el sujeto de la imagen de referencia ligado a `@Actor-1` y la referencia de movimiento ligada a `@video1` en el proceso de generación.

## Parámetros de la solicitud

### Campos generales

**model** `string` *required*

Hay dos niveles de modelo disponibles:

| Modelo | Posicionamiento | Casos de uso |
| - | - | - |
| `skyreels-v4-fast` | Prioriza velocidad | Vistas previas rápidas, generación por lotes, contenido diario |
| `skyreels-v4-std` | Prioriza calidad (precio 25\~30% superior al Fast) | Tomas clave, requisitos de alto detalle, entregas formales |

> [!WARNING]
>
> **El campo `model` debe proporcionarse explícitamente — no tiene valor por defecto.**

> [!TIP]
>
> **El precio está fuertemente ligado a la resolución y al uso de `ref_videos`**: 1080p es significativamente más caro que 480p / 720p; los niveles con `ref_videos` (entrada de video) cuestan \~1.5 \~ 2× en comparación con los que no lo usan. Aún no se admite la salida simultánea de audio y video.

**nsfw\_check** `boolean` (default: false)

Indica si se debe moderar el contenido antes de enviar la tarea de vídeo.

* `true`: revisar los prompts y las imágenes de entrada con `omni-moderation-latest`
* `false` u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)

**prompt** `string` *required*

Prompt de texto, máximo **1280 tokens**

Describa escenas, sujetos, acciones y estilos en detalle para obtener mejores resultados.

Al usar `ref_images` / `ref_videos` / `mid_frame_images`, el `prompt` **debe contener** el `@tag` correspondiente (por ejemplo, `@Actor-1`, `@video1`, `@image1`).

Ejemplo: `"@Actor-1 walks through a neon-lit street at night."`

**duration** `integer` (default: 5)

Duración del video de salida (segundos)

* Rango: `[3, 15]`
* Por defecto: `5`

> [!WARNING]
>
> Cuando se proporciona `ref_videos.type=reference`, `duration` se sobrescribe con la longitud del video de referencia (máx. 10 segundos).

**resolution** `string` (default: 1080p)

Resolución del video

Opciones:

* `480p`
* `720p`
* `1080p` (por defecto)

**aspect\_ratio** `string` (default: 16:9)

Proporción de aspecto

Opciones:

* `16:9` (por defecto)
* `4:3`
* `1:1`
* `9:16`
* `3:4`

> [!WARNING]
>
> **`aspect_ratio` se ignora en modo I2V** (la proporción de salida la determina la imagen de entrada); también se ignora cuando Omni se combina con `ref_videos`.

**prompt\_optimizer** `boolean` (default: true)

Si se debe optimizar el prompt automáticamente

Cuando está activado, el sistema optimiza automáticamente su prompt para obtener mejores resultados.

### Campos específicos de I2V

**first\_frame\_image** `string`

URL de la imagen del primer fotograma (jpg / jpeg / png / gif / bmp)

Cuando se proporciona, esta imagen se utiliza como **fotograma inicial** del video.

**end\_frame\_image** `string`

URL de la imagen del último fotograma (jpg / jpeg / png / gif / bmp)

Cuando se proporciona, esta imagen se utiliza como **fotograma final** del video. Puede combinarse con `first_frame_image` para el control de primer y último fotograma.

**mid\_frame\_images** `object[]`

Lista de fotogramas clave intermedios, **hasta 6**. Cada elemento tiene la siguiente estructura:

**elemento mid\_frame\_images**

**tag** `string` *required*

Debe comenzar con `@` y aparecer en el `prompt`, por ejemplo, `@image1`

**image\_url** `string` *required*

URL de la imagen (jpg / jpeg / png / gif / bmp)

**time\_stamp** `integer` (default: -1)

Marca temporal de aparición (segundos). Por defecto `-1` (sin especificar); cuando se especifica, debe cumplir `0 < time_stamp < duration`.

### Campos específicos de Omni

**ref\_images** `object[]`

Lista de imágenes de referencia (todos los elementos deben compartir el mismo `type`). Cada elemento tiene la siguiente estructura:

**elemento ref\_images**

**tag** `string` *required*

Debe comenzar con `@` y aparecer en el `prompt`, por ejemplo, `@Actor-1`

**type** `string` *required*

Tipo de referencia:

* `image` - Imagen de referencia regular (longitud de lista 1~~3; cada `image_urls` con longitud 1~~5)
* `grid` - Collage en cuadrícula, es decir, una sola imagen compuesta por múltiples mosaicos (por ejemplo, 2×2, 3×3); la longitud de la lista debe ser 1, `image_urls` debe ser 1 imagen

**image\_urls** `string[]` *required*

Array de URLs de imágenes

**audio\_url** `string`

URL de audio de voz (**solo soportado cuando `type=image`**, duración del audio ≤ 15 segundos)

**ref\_videos** `object[]`

Lista de videos de referencia, **hasta 1**. Cada elemento tiene la siguiente estructura:

**elemento ref\_videos**

**tag** `string` *required*

Debe comenzar con `@` y aparecer en el `prompt`, por ejemplo, `@video1`

**type** `string` *required*

Tipo de referencia:

* `reference` - Referencia de movimiento / sujeto, **sobrescribe `duration`** (sigue la longitud del video de referencia, máx. 10 segundos), incluye por defecto el audio del video de entrada; **puede combinarse con `ref_images.type=image`**
* `extend` - Extensión de video, facturada según la `duration` solicitada; **no puede combinarse con `ref_images`**

**video\_url** `string` *required*

URL del video (MP4 / MOV, duración ≤ 15 segundos)

## Escenarios soportados

Los siguientes escenarios son **soportados tanto por** `skyreels-v4-fast` como por `skyreels-v4-std`:

| Escenario | Modo | Campos requeridos | Caso de uso típico |
| - | - | - | - |
| Text-to-Video | T2V | `prompt` | Generación basada en texto puro, tomas conceptuales rápidas |
| Image-to-Video - Primer fotograma | I2V | `first_frame_image` | Imagen estática a video con un fotograma inicial especificado |
| Image-to-Video - Último fotograma | I2V | `end_frame_image` | Especifica el fotograma de cierre |
| Image-to-Video - Fotogramas clave | I2V | `mid_frame_images` (1 \~ 6) | Primer + último + fotogramas clave intermedios para un ritmo preciso |
| Omni Sujeto único/múltiple | Omni | `ref_images` (`type=image`) | Consistencia de personaje, encuadre multi-sujeto |
| Omni Collage en cuadrícula | Omni | `ref_images` (`type=grid`, 1 imagen) | Videos paso a paso (tutoriales, recetas, demos) |
| Omni Referencia de movimiento | Omni | `ref_videos` (`type=reference`) | Replicar el movimiento, sujeto o estilo de un video de referencia |
| Omni Extensión de video | Omni | `ref_videos` (`type=extend`) | Continuar un video existente con contenido nuevo |
| Omni Sincronización de audio | Omni | `ref_images` (`type=image`) + `audio_url` | Narración con humano digital, lip-sync impulsado por audio |

## Restricciones de parámetros

Violar cualquiera de las siguientes hará que la solicitud sea rechazada con una respuesta **422**, **sin facturación**:

| Parámetro | Restricción |
| - | - |
| `prompt` | Máximo 1280 tokens |
| `duration` | `[3, 15]` segundos; sobrescrito por la longitud del video de referencia (máx. 10s) cuando `ref_videos.type=reference` |
| `resolution` | Solo `480p` / `720p` / `1080p` |
| `aspect_ratio` | `16:9` / `4:3` / `1:1` / `9:16` / `3:4`; ignorado en I2V; ignorado cuando Omni incluye `ref_videos` |
| `mid_frame_images` | Hasta 6; `time_stamp` debe ser `-1` o estar dentro de `(0, duration)` |
| `ref_images` general | Todos los elementos deben compartir el mismo `type`; no puede coexistir con campos I2V |
| `ref_images.type=grid` | Longitud de lista debe ser 1; `image_urls` debe ser 1 imagen |
| `ref_images.type=image` | Longitud de lista 1 \~ 3; cada `image_urls` con longitud 1 \~ 5 |
| `ref_images.audio_url` | Solo soportado cuando `type=image`, audio ≤ 15 segundos |
| `ref_videos` | Hasta 1; `video_url` MP4 / MOV, ≤ 15 segundos |
| `ref_videos.type=reference` | Sobrescribe la `duration` solicitada (máx. 10s), puede combinarse con `ref_images.type=image`, incluye por defecto el audio del video de entrada |
| `ref_videos.type=extend` | Facturado por la `duration` solicitada; **no puede combinarse con `ref_images`** |
| Campo `tag` | Debe comenzar con `@` y aparecer en el `prompt` |
| Exclusión I2V / Omni | Los campos I2V y Omni no pueden usarse juntos |

## Respuesta

**code** `integer`

Código de estado de la respuesta, 200 en caso de éxito

**data** `array`

Array de datos de la respuesta

**Elementos del array**

**status** `string`

Estado de la tarea, `submitted` al enviarse inicialmente

**task\_id** `string`

Identificador único de la tarea para consultar el estado y los resultados

## Ejemplos de solicitud

### Caso 1: Texto a video (mínimo)

```json theme={null}
{
  "model": "skyreels-v4-fast",
  "prompt": "A serene forest at sunset with golden light filtering through the trees."
}
```

### Caso 2: Texto a video (parámetros completos)

```json theme={null}
{
  "model": "skyreels-v4-std",
  "prompt": "A serene forest at sunset.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "prompt_optimizer": true
}
```

### Caso 3: Imagen a video - Primer fotograma

```json theme={null}
{
  "model": "skyreels-v4-fast",
  "prompt": "Slowly pull the camera back to reveal the entire scene.",
  "first_frame_image": "https://example.com/start.png",
  "duration": 5
}
```

### Caso 4: Imagen a video - Primer/Último fotograma + fotogramas clave intermedios

```json theme={null}
{
  "model": "skyreels-v4-std",
  "prompt": "The King summons a flying dragon. @image1 The dragon lowers. The King mounts and flies away.",
  "duration": 8,
  "resolution": "1080p",
  "first_frame_image": "https://example.com/k2v_0.png",
  "end_frame_image":   "https://example.com/k2v_2.png",
  "mid_frame_images": [
    { "tag": "@image1", "image_url": "https://example.com/k2v_1.png", "time_stamp": 3 }
  ]
}
```

### Caso 5: Omni - Referencia de sujeto único

```json theme={null}
{
  "model": "skyreels-v4-fast",
  "prompt": "@Actor-1 walks through a neon-lit street at night.",
  "ref_images": [
    { "tag": "@Actor-1", "type": "image", "image_urls": ["https://example.com/actor.jpg"] }
  ]
}
```

### Caso 6: Omni - Multi-sujeto + referencia de movimiento por video

```json theme={null}
{
  "model": "skyreels-v4-fast",
  "prompt": "The man from @image_1 imitates the move on the left in @video_1. The woman from @image_2 imitates the right side.",
  "duration": 5,
  "ref_images": [
    { "tag": "@image_1", "type": "image", "image_urls": ["https://example.com/a.png"] },
    { "tag": "@image_2", "type": "image", "image_urls": ["https://example.com/b.png"] }
  ],
  "ref_videos": [
    { "tag": "@video_1", "type": "reference", "video_url": "https://example.com/motion.mp4" }
  ]
}
```

> [!WARNING]
>
> Este caso usa `ref_videos.type=reference`, por lo que **la `duration` solicitada será sobrescrita por la longitud real del video de referencia** (máx. 10 segundos). Aunque aquí se pase `"duration": 5`, la duración final del video sigue la del video de referencia.

### Caso 7: Omni - Collage en cuadrícula

```json theme={null}
{
  "model": "skyreels-v4-fast",
  "prompt": "Create a video showing how to make tomato and egg noodles based on @image1.",
  "ref_images": [
    { "tag": "@image1", "type": "grid", "image_urls": ["https://example.com/recipe_grid.png"] }
  ]
}
```

### Caso 8: Omni - Extensión de video (extend)

```json theme={null}
{
  "model": "skyreels-v4-fast",
  "prompt": "Video extended @video1, someone walks over and sits on the sofa.",
  "duration": 8,
  "ref_videos": [
    { "tag": "@video1", "type": "extend", "video_url": "https://example.com/source.mp4" }
  ]
}
```

### Caso 9: Omni - Sincronización de audio (impulsado por voz)

```json theme={null}
{
  "model": "skyreels-v4-std",
  "prompt": "@Actor-1 speaks with a calm tone.",
  "ref_images": [
    {
      "tag": "@Actor-1",
      "type": "image",
      "image_urls": ["https://example.com/actor.jpg"],
      "audio_url":  "https://example.com/voice.mp3"
    }
  ]
}
```

> [!NOTE]
>
> **Consultar resultados de la tarea**
>
> La generación de video es una tarea asíncrona que devuelve un `task_id` al enviarse. Use el endpoint [Obtener estado de la tarea](https://gccai.heqingsong.uk/es/api-reference/tasks/status.md) para consultar el progreso y los resultados de la generación.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.