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": "happyhorse-1.1",
    "prompt": "A little girl walking down the road, cinematic feel",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

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

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "happyhorse-1.1",
    "prompt": "A little girl walking down the road, cinematic feel",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

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

​
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

​
Enrutamiento de modos

happyhorse-1.1 es la entrada unificada para Text-to-Video / Image-to-Video / Reference-Image-to-Video. El backend determina automáticamente el modo según los parámetros entrantes. Todos los modos se facturan con la misma regla (solo resolución × segundos):
Campos que envíaSe enruta aDescripción del modo
Solo promptText-to-Video (T2V)Genera video únicamente a partir de texto
prompt + first_frame_imageImage-to-Video (I2V)Anima desde una imagen del primer fotograma
prompt + image_urls (1–9 imágenes)Reference-Image-to-Video (R2V)Genera una nueva escena a partir de imágenes de referencia
Prioridad de enrutamiento (de alta a baja): first_frame_image > image_urls > solo prompt. Reglas de exclusión mutua: los dos campos de medios (first_frame_image / image_urls) son mutuamente excluyentes. Pasar ambos campos mutuamente excluyentes a la vez devuelve 400 mixed_media_not_allowed.

​
Parámetros de la solicitud

​
model
string
requerido
Nombre del modelo de generación de video, fijado como happyhorse-1.1
​
prompt
string
Descripción del contenido del video, hasta 2500 caracteres; no puede contener tokens especialesEjemplo: "A little girl walking down the road, cinematic feel"
​
first_frame_image
string
Imagen del primer fotograma, activa I2V (Image-to-Video). Admite URL o base64 (data:image/<mime>;base64,<payload>, el gateway la sube automáticamente a OSS)Mutuamente excluyente con image_urls
Requisitos de la imagen del primer fotograma:
  • Formato: JPEG / JPG / PNG / BMP / WEBP
  • Lado corto: ≥ 300px
  • Proporción de aspecto: 1:2.5 a 2.5:1
  • Tamaño del archivo: ≤ 10MB
​
image_urls
array<string>
Array de imágenes (Modo R2V): 1–9 imágenes, usadas como referencias de sujeto/estilo para generar una nueva escenaAdmite URL o base64Mutuamente excluyente con first_frame_image
Requisitos de las imágenes de referencia:
  • Formato: JPEG / JPG / PNG / BMP / WEBP
  • Lado corto: ≥ 720p recomendado
  • Proporción de aspecto: corto / largo ≥ 0.4
  • Tamaño del archivo: ≤ 10MB
  • Cantidad: 1–9 imágenes
​
resolution
string
predeterminado:"1080P"
Resolución del video (afecta a la facturación)Opciones:
  • 720P - Estándar
  • 1080P - Alta definición (por defecto)
​
duration
integer
predeterminado:"5"
Duración del video en segundos (afecta a la facturación)Rango soportado: cualquier entero de 3 a 15Por defecto: 5
​
size
string
predeterminado:"16:9"
Proporción de aspectoFormatos soportados:
  • 16:9 - Paisaje panorámico (por defecto)
  • 9:16 - Retrato
  • 1:1 - Cuadrado
  • 4:3 - Paisaje
  • 3:4 - Retrato
Ignorado en modo I2V — la proporción de aspecto de salida se determina automáticamente por el medio de entrada (imagen del primer fotograma)
​
watermark
boolean
predeterminado:"false"
Si se debe añadir una marca de agua al video generado
  • true: añadir marca de agua
  • false: no añadir marca de agua (por defecto)
​
seed
integer
Semilla aleatoria usada para controlar la aleatoriedad del contenido generadoRango de valores: [0, 2147483647]. Si se omite, se usa una semilla aleatoria.
  • Para solicitudes idénticas, el modelo genera resultados diferentes al recibir valores de seed diferentes (por ejemplo, al omitir el seed)
  • Para solicitudes idénticas, el modelo genera resultados similares al recibir el mismo valor de seed, pero no se garantiza consistencia exacta

​
Respuesta

​
code
integer
Código de estado de la respuesta, 200 en caso de éxito
​
data
array
Array de datos de la respuesta

​
Casos de uso

​
Caso 1: Texto a video T2V (Solicitud más simple)

{
  "model": "happyhorse-1.1",
  "prompt": "A little girl walking down the road, cinematic feel"
}

​
Caso 2: Texto a video T2V (Parámetros completos)

{
  "model": "happyhorse-1.1",
  "prompt": "A coastal road at sunset, slow-motion camera push-in, cinematic feel",
  "resolution": "1080P",
  "size": "16:9",
  "duration": 8,
  "seed": 42
}

​
Caso 3: Imagen a video I2V (first_frame_image)

{
  "model": "happyhorse-1.1",
  "prompt": "Bring the scene in the image to life",
  "first_frame_image": "https://example.com/first_frame.png",
  "resolution": "1080P",
  "duration": 5
}

​
Caso 4: Referencia-Imagen a video R2V (múltiples referencias)

{
  "model": "happyhorse-1.1",
  "prompt": "The protagonist from image 1 runs through the scene from image 2, then picks up the prop from image 3. Keep a 3D cartoon style with smooth motion.",
  "image_urls": [
    "https://example.com/img_01.jpg",
    "https://example.com/img_02.png",
    "https://example.com/img_03.jpeg"
  ],
  "resolution": "1080P",
  "size": "16:9",
  "duration": 5
}

​
Caso 5: 720P para ahorrar costos

{
  "model": "happyhorse-1.1",
  "prompt": "Waves crashing on the beach at sunset",
  "resolution": "720P",
  "size": "16:9",
  "duration": 5
}

​
Guía de selección de modo

RequisitoEnfoque recomendado
Generar video solo a partir de textoPasar solo prompt (T2V)
Hacer que una imagen “cobre vida” (usarla como primer fotograma)Pasar first_frame_image (I2V)
Generar una nueva escena a partir de un conjunto de imágenes de referenciaPasar image_urls (1–9, R2V)
Ahorrar costosUsar resolution: "720P"

​
Consejos de uso

  1. Lógica de entrada unificada: los campos de entrada determinan el modo. Tenga en cuenta que los dos campos de medios (first_frame_image / image_urls) son mutuamente excluyentes
  2. size solo efectivo en T2V/R2V: en el modo I2V, size se ignora — la proporción de aspecto de salida está determinada por el medio de entrada
  3. Duración: de 5 a 10 segundos es el punto óptimo. Demasiado corta causa movimiento entrecortado; demasiado larga aumenta significativamente el tiempo de procesamiento upstream
  4. Calidad de la imagen del primer fotograma: clara, bien compuesta, sujeto centrado — mejora significativamente la salida I2V
  5. Redacción del prompt: describa movimiento / cámara / atmósfera (por ejemplo, “slow push-in, cinematic, warm tones”) para obtener mejores resultados que con descripciones puramente estáticas de la escena
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.