Saltar al contenido principal
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.apimart.ai/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
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPEY5H3NQ2W8D7T6VB3F9GR4"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt

Use this file to discover all available pages before exploring further.

curl --request POST \
  --url https://api.apimart.ai/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
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPEY5H3NQ2W8D7T6VB3F9GR4"
    }
  ]
}

​
Autorización

​
Authorization
string
requerido
Todos los endpoints de la API requieren autenticación mediante Bearer TokenObtenga su API Key:Visite la página de gestión de API Keys para obtener su API KeyAñá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:
ModoActivadorCapacidad
T2V (Text-to-Video)Solo prompt + campos generalesGeneración basada únicamente en texto
I2V (Image-to-Video)Cualquiera de first_frame_image / end_frame_image / mid_frame_imagesControl de primer/último/fotograma clave
Omni (Referencia multimodal)Cualquiera de ref_images / ref_videosReferencia de sujeto, collage en cuadrícula, referencia de movimiento, extensión de video, sincronización de audio
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.
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
requerido
Hay dos niveles de modelo disponibles:
ModeloPosicionamientoCasos de uso
skyreels-v4-fastPrioriza velocidadVistas previas rápidas, generación por lotes, contenido diario
skyreels-v4-stdPrioriza calidad (precio 25~30% superior al Fast)Tomas clave, requisitos de alto detalle, entregas formales
El campo model debe proporcionarse explícitamente — no tiene valor por defecto.
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.
​
prompt
string
requerido
Prompt de texto, máximo 1280 tokensDescriba 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
predeterminado:"5"
Duración del video de salida (segundos)
  • Rango: [3, 15]
  • Por defecto: 5
Cuando se proporciona ref_videos.type=reference, duration se sobrescribe con la longitud del video de referencia (máx. 10 segundos).
​
resolution
string
predeterminado:"1080p"
Resolución del videoOpciones:
  • 480p
  • 720p
  • 1080p (por defecto)
​
aspect_ratio
string
predeterminado:"16:9"
Proporción de aspectoOpciones:
  • 16:9 (por defecto)
  • 4:3
  • 1:1
  • 9:16
  • 3:4
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
predeterminado:"true"
Si se debe optimizar el prompt automáticamenteCuando 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:

​
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:
​
ref_videos
object[]
Lista de videos de referencia, hasta 1. Cada elemento tiene la siguiente estructura:

​
Escenarios soportados

Los siguientes escenarios son soportados tanto por skyreels-v4-fast como por skyreels-v4-std:
EscenarioModoCampos requeridosCaso de uso típico
Text-to-VideoT2VpromptGeneración basada en texto puro, tomas conceptuales rápidas
Image-to-Video - Primer fotogramaI2Vfirst_frame_imageImagen estática a video con un fotograma inicial especificado
Image-to-Video - Último fotogramaI2Vend_frame_imageEspecifica el fotograma de cierre
Image-to-Video - Fotogramas claveI2Vmid_frame_images (1 ~ 6)Primer + último + fotogramas clave intermedios para un ritmo preciso
Omni Sujeto único/múltipleOmniref_images (type=image)Consistencia de personaje, encuadre multi-sujeto
Omni Collage en cuadrículaOmniref_images (type=grid, 1 imagen)Videos paso a paso (tutoriales, recetas, demos)
Omni Referencia de movimientoOmniref_videos (type=reference)Replicar el movimiento, sujeto o estilo de un video de referencia
Omni Extensión de videoOmniref_videos (type=extend)Continuar un video existente con contenido nuevo
Omni Sincronización de audioOmniref_images (type=image) + audio_urlNarració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ámetroRestricción
promptMáximo 1280 tokens
duration[3, 15] segundos; sobrescrito por la longitud del video de referencia (máx. 10s) cuando ref_videos.type=reference
resolutionSolo 480p / 720p / 1080p
aspect_ratio16:9 / 4:3 / 1:1 / 9:16 / 3:4; ignorado en I2V; ignorado cuando Omni incluye ref_videos
mid_frame_imagesHasta 6; time_stamp debe ser -1 o estar dentro de (0, duration)
ref_images generalTodos los elementos deben compartir el mismo type; no puede coexistir con campos I2V
ref_images.type=gridLongitud de lista debe ser 1; image_urls debe ser 1 imagen
ref_images.type=imageLongitud de lista 1 ~ 3; cada image_urls con longitud 1 ~ 5
ref_images.audio_urlSolo soportado cuando type=image, audio ≤ 15 segundos
ref_videosHasta 1; video_url MP4 / MOV, ≤ 15 segundos
ref_videos.type=referenceSobrescribe 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=extendFacturado por la duration solicitada; no puede combinarse con ref_images
Campo tagDebe comenzar con @ y aparecer en el prompt
Exclusión I2V / OmniLos 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

​
Ejemplos de solicitud

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

{
  "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)

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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" }
  ]
}
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

{
  "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)

{
  "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)

{
  "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"
    }
  ]
}
Consultar resultados de la tareaLa generación de video es una tarea asíncrona que devuelve un task_id al enviarse. Use el endpoint Obtener estado de la tarea para consultar el progreso y los resultados de la generación.