Saltar al contenido
Referencia de API
Referencia de API

Kling Editar video

Usa el endpoint de edición de video para crear una Task asíncrona.

Ver Markdown
01

Descripción general

Usa el endpoint de edición de video con un modelo compatible. Usa el ID de Task devuelto para recuperar su estado, o proporciona callback_url para las entregas documentadas a continuación.

Inicio rápido

  1. Cree una Clave de API y establézcala como RUNAPI_API_KEY.
  2. Elija un modelo compatible y envíe una solicitud POST cuyo cuerpo coincida con el esquema de ese modelo.
  3. Almacena el ID de tarea devuelto, luego sondea hasta alcanzar un estado terminal o gestiona las devoluciones de llamada documentadas a continuación.

Endpoint

POST /api/v1/kling/edit_video
URL base
https://runapi.ai
Versión de la API
v1
Autenticación
Authorization: Bearer YOUR_API_TOKEN
02

Modelos compatibles

Abra una página de modelo para conocer los precios actuales, los límites de velocidad y los detalles de uso comercial.

03

Esquema de solicitud

Cuerpo JSON

Los campos y los valores permitidos dependen del modelo seleccionado. Cuando se proporciona, callback_url recibe las entregas de tareas documentadas a continuación.

kling-v3-omni-edit10 campos
aspect_ratiostring
Opcional

Relación de aspecto de salida; las solicitudes solo de fuente requieren auto.

Valores permitidos: auto, 16:9, 9:16, 1:1
callback_urlstring
Opcional

URL de webhook para notificaciones asíncronas.

duration_secondsinteger
Opcional

Duración de salida en segundos.

Valores permitidos: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 Valor predeterminado: 5
enable_soundboolean
Opcional

Activar la generación de sonido sincronizado.

Valor predeterminado: false
modelstring
Obligatorio

Identificador del modelo.

output_resolutionstring
Opcional

Resolución de salida.

Valores permitidos: 720p, 1080p, 4k Valor predeterminado: 720p
promptstring
Obligatorio

Descripción del video.

Rango: 1 - 2500
reference_image_urlsarray
Opcional

URL de imágenes de referencia ordenadas.

Rango de elementos: 1 - 4
source_task_idstring
Opcional

ID de tarea compatible completada; no se puede combinar con source_video_url.

source_video_urlstring
Opcional

URL pública de vídeo de origen; no se puede combinar con source_task_id.

kling-v3-omni-reference10 campos
aspect_ratiostring
Opcional

Relación de aspecto de salida; las solicitudes solo de fuente requieren auto.

Valores permitidos: auto, 16:9, 9:16, 1:1
callback_urlstring
Opcional

URL de webhook para notificaciones asíncronas.

duration_secondsinteger
Opcional

Duración de salida en segundos.

Valores permitidos: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 Valor predeterminado: 5
enable_soundboolean
Opcional

Activar la generación de sonido sincronizado; las solicitudes de video de origen requieren false.

Valor predeterminado: false
modelstring
Obligatorio

Identificador del modelo.

output_resolutionstring
Opcional

Resolución de salida.

Valores permitidos: 720p, 1080p, 4k Valor predeterminado: 720p
promptstring
Obligatorio

Descripción del video.

Rango: 1 - 2500
reference_image_urlsarray
Opcional

URL de imágenes de referencia ordenadas.

Rango de elementos: 1 - 4
source_task_idstring
Opcional

ID de tarea compatible completada; no se puede combinar con source_video_url.

source_video_urlstring
Opcional

URL pública de vídeo de origen; no se puede combinar con source_task_id.

Reglas condicionales

Estos requisitos se aplican cuando todas las condiciones enumeradas coinciden.

  1. Cuando model = kling-v3-omni-edit, source_task_id = {"present" => false}, source_video_url = {"present" => false}
    Obligatorio
    No aceptado
  2. Cuando model = kling-v3-omni-edit, source_video_url = {"present" => true}
    Obligatorio
    No aceptado
    source_task_id
  3. Cuando model = kling-v3-omni-edit, source_task_id = {"present" => true}
    Obligatorio
    No aceptado
    source_video_url
  4. Cuando model = kling-v3-omni-edit, reference_image_urls = {"present" => false}, source_video_url = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  5. Cuando model = kling-v3-omni-edit, reference_image_urls = {"present" => false}, source_task_id = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  6. Cuando model = kling-v3-omni-edit, reference_image_urls = {"present" => true}, source_video_url = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  7. Cuando model = kling-v3-omni-edit, reference_image_urls = {"present" => true}, source_task_id = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  8. Cuando model = kling-v3-omni-reference, source_task_id = {"present" => false}, source_video_url = {"present" => false}
    Obligatorio
    No aceptado
  9. Cuando model = kling-v3-omni-reference, source_video_url = {"present" => true}
    Obligatorio
    No aceptado
    source_task_id
  10. Cuando model = kling-v3-omni-reference, source_task_id = {"present" => true}
    Obligatorio
    No aceptado
    source_video_url
  11. Cuando model = kling-v3-omni-reference, reference_image_urls = {"present" => false}, source_video_url = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  12. Cuando model = kling-v3-omni-reference, reference_image_urls = {"present" => false}, source_task_id = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  13. Cuando model = kling-v3-omni-reference, reference_image_urls = {"present" => true}, source_video_url = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
  14. Cuando model = kling-v3-omni-reference, reference_image_urls = {"present" => true}, source_task_id = {"present" => true}
    Obligatorio
    aspect_ratio
    No aceptado
04

Crear aceptación

HTTP 202

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Consulta en proceso

HTTP 200

GET /api/v1/kling/edit_video/:id

Esquema de respuesta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Consulta completada

HTTP 200

GET /api/v1/kling/edit_video/:id

Esquema de respuesta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
07

Consulta fallida

HTTP 200

GET /api/v1/kling/edit_video/:id

Esquema de respuesta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Devolución de llamada del cliente: completado

HTTP 200

POST callback_url

Esquema de respuesta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
09

Devolución de llamada del cliente: fallido

HTTP 200

POST callback_url

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

Errores

HTTP 401

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Authentication required"
}
11

Errores

HTTP 401

GET /api/v1/kling/edit_video/:id

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Authentication required"
}
12

Errores

HTTP 400

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Mensaje de error legible por personas.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Resumen de validación legible por personas.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Ejemplo de respuesta

JSON 
{
  "error": "model must be one of: kling-v3-omni-edit, kling-v3-omni-reference"
}
13

Errores

HTTP 402

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Insufficient balance"
}
14

Errores

HTTP 429

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "API key credit limit exceeded"
}
15

Errores

HTTP 409

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

Errores

HTTP 429

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

Errores

HTTP 503

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

Errores

HTTP 504

POST /api/v1/kling/edit_video

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "The request timed out"
}
19

Errores

HTTP 404

GET /api/v1/kling/edit_video/:id

Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

Ejemplos de código generados

Usa cURL directamente o instala un SDK para tu lenguaje. Cada muestra envía la solicitud validada que se muestra en esta referencia.

Instalar

Shell 
pip install runapi-kling
PYTHON 
import os
from runapi.kling import KlingClient

client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.edit_video.create(
  model="kling-v3-omni-edit",
  prompt="Turn the source into a hand-painted watercolor scene.",
  source_video_url="https://cdn.runapi.ai/public/samples/video.mp4",
  reference_image_urls=["https://cdn.runapi.ai/public/samples/image.jpg"],
  duration_seconds=8,
  output_resolution="1080p",
  enable_sound=True,
  aspect_ratio="16:9"
)