{
  "openapi": "3.1.0",
  "info": {
    "title": "VideosTemporales Agent API",
    "version": "1.2.0",
    "description": "API para agentes de IA y automatizaciones que necesitan entregar un vídeo temporal a una persona. El resultado principal es share_url: una página humana de VideosTemporales que debe devolverse al usuario. No se expone una URL directa al archivo."
  },
  "servers": [
    {
      "url": "https://api.videostemporales.net/v1"
    }
  ],
  "paths": {
    "/capabilities": {
      "get": {
        "operationId": "getAgentCapabilities",
        "summary": "Consultar límites y formas de subida disponibles",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Capacidades de la clave, cuota disponible e instrucción de entrega al humano"
          },
          "401": {
            "description": "Clave API no válida"
          }
        }
      }
    },
    "/upload": {
      "post": {
        "operationId": "uploadTemporaryVideo",
        "summary": "Subir un vídeo temporal y obtener el enlace que debe recibir el humano",
        "description": "Admite dos modos: multipart/form-data con el campo video, o application/json con source_url/file.download_url para URLs HTTPS temporales generadas por plataformas de agentes. Tras completar la subida, devuelve share_url. Entrega share_url al usuario humano exactamente como enlace de visualización; no intentes obtener ni construir una URL directa al archivo.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "video"
                ],
                "properties": {
                  "video": {
                    "type": "string",
                    "format": "binary"
                  },
                  "ttl_minutes": {
                    "type": "integer",
                    "default": 1440,
                    "description": "Duración del enlace. Usa uno de los valores anunciados por capabilities."
                  },
                  "custom_name": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "lock_first_viewer": {
                    "type": "boolean",
                    "default": false
                  },
                  "share_verification_data": {
                    "type": "boolean",
                    "default": false
                  },
                  "anti_repost_watermark": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL HTTPS temporal y públicamente accesible desde la que VideosTemporales descargará el vídeo."
                  },
                  "file": {
                    "type": "object",
                    "description": "Forma compatible con plataformas de agentes que entregan archivos mediante download_url.",
                    "properties": {
                      "download_url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "file_id": {
                        "type": "string"
                      },
                      "mime_type": {
                        "type": "string"
                      },
                      "file_name": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "download_url"
                    ]
                  },
                  "file_name": {
                    "type": "string",
                    "description": "Nombre opcional si source_url no contiene una extensión útil."
                  },
                  "ttl_minutes": {
                    "type": "integer",
                    "default": 1440
                  },
                  "custom_name": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "lock_first_viewer": {
                    "type": "boolean",
                    "default": false
                  },
                  "share_verification_data": {
                    "type": "boolean",
                    "default": false
                  },
                  "anti_repost_watermark": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "source_url"
                    ]
                  },
                  {
                    "required": [
                      "file"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vídeo guardado. share_url es el único enlace que debe entregarse al humano.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "code",
                    "share_url",
                    "expires_at",
                    "ttl_minutes",
                    "delivery",
                    "instruction"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "code": {
                      "type": "string"
                    },
                    "share_url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Devuelve este enlace al usuario humano."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "ttl_minutes": {
                      "type": "integer"
                    },
                    "size_bytes": {
                      "type": "integer"
                    },
                    "duration_seconds": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "status": {
                      "type": "string"
                    },
                    "delivery": {
                      "type": "string",
                      "const": "human_view_page"
                    },
                    "agent_identity_type": {
                      "type": "string"
                    },
                    "input_mode": {
                      "type": "string",
                      "enum": [
                        "multipart",
                        "remote_url"
                      ]
                    },
                    "instruction": {
                      "type": "string"
                    },
                    "api_version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Archivo, URL o parámetros no válidos"
          },
          "401": {
            "description": "Clave API no válida"
          },
          "403": {
            "description": "La clave no tiene el scope necesario o la importación por URL está deshabilitada"
          },
          "413": {
            "description": "El vídeo supera el límite aplicable"
          },
          "429": {
            "description": "Límite horario o cuota de bytes alcanzados"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "VT_AGENT_API_KEY"
      }
    }
  }
}