{
  "openapi": "3.0.3",
  "info": {
    "title": "Qubrid Video API",
    "version": "1.0.0",
    "description": "Generate videos from text prompts with optional image and audio inputs using advanced AI models."
  },
  "servers": [
    {
      "url": "https://platform.qubrid.com/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key"
      }
    },
    "schemas": {
      "VideoGenerationRequest": {
        "type": "object",
        "required": ["model"],
        "properties": {
          "model": {
            "type": "string",
            "example": "p-video",
            "description": "The video generation model to use."
          },
          "prompt": {
            "type": "string",
            "example": "A butterfly flying through a flower garden",
            "description": "Optional text prompt describing the video to generate."
          },
          "duration": {
            "type": "integer",
            "example": 5,
            "description": "Duration of the generated video in seconds."
          },
          "resolution": {
            "type": "string",
            "example": "720p",
            "description": "Output video resolution."
          },
          "fps": {
            "type": "integer",
            "example": 24,
            "description": "Frames per second for the generated video."
          },
          "aspect_ratio": {
            "type": "string",
            "example": "16:9",
            "description": "Aspect ratio of the output video."
          },
          "image": {
            "type": "string",
            "nullable": true,
            "default": null,
            "example": "https://example.com/input-image.jpg",
            "description": "Optional input image URL to guide or initialize video generation."
          },
          "audio": {
            "type": "string",
            "nullable": true,
            "default": null,
            "example": "https://example.com/audio.mp3",
            "description": "Optional input audio URL to include in the generated video."
          },
          "draft": {
            "type": "boolean",
            "default": false,
            "description": "Whether to generate a draft/preview version of the video."
          },
          "save_audio": {
            "type": "boolean",
            "default": true,
            "description": "Whether to retain the provided audio in the final generated video."
          },
          "prompt_upsampling": {
            "type": "boolean",
            "default": true,
            "description": "Whether to automatically enhance or expand the prompt before generation."
          }
        }
      },

      "VideoGenerationMultipartRequest": {
        "type": "object",
        "required": ["model"],
        "properties": {
          "model": {
            "type": "string",
            "example": "p-video",
            "description": "The video generation model to use."
          },
          "prompt": {
            "type": "string",
            "example": "A butterfly flying through a flower garden",
            "description": "Optional text prompt describing the video to generate."
          },
          "duration": {
            "type": "string",
            "example": "5",
            "description": "Duration of the generated video in seconds."
          },
          "resolution": {
            "type": "string",
            "example": "720p",
            "description": "Output video resolution."
          },
          "fps": {
            "type": "string",
            "example": "24",
            "description": "Frames per second for the generated video."
          },
          "aspect_ratio": {
            "type": "string",
            "example": "16:9",
            "description": "Aspect ratio of the output video."
          },
          "image": {
            "type": "string",
            "nullable": true,
            "default": null,
            "example": "https://example.com/input-image.jpg",
            "description": "Optional image URL input when sending multipart form data."
          },
          "audio": {
            "type": "string",
            "nullable": true,
            "default": null,
            "example": "https://example.com/audio.mp3",
            "description": "Optional audio URL input when sending multipart form data."
          },
          "image_file": {
            "type": "string",
            "format": "binary",
            "description": "Optional image file upload."
          },
          "audio_file": {
            "type": "string",
            "format": "binary",
            "description": "Optional audio file upload."
          },
          "draft": {
            "type": "string",
            "example": "false",
            "description": "Whether to generate a draft/preview version of the video."
          },
          "save_audio": {
            "type": "string",
            "example": "true",
            "description": "Whether to retain the provided audio in the final generated video."
          },
          "prompt_upsampling": {
            "type": "string",
            "example": "true",
            "description": "Whether to automatically enhance or expand the prompt before generation."
          }
        }
      },

      "VideoGenerationResponse": {
        "type": "object",
        "properties": {
          "created": {
            "type": "integer",
            "example": 1710000000,
            "description": "Unix timestamp when the video generation request was created."
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "example": "https://cdn.qubrid.com/generated/video.mp4",
                  "description": "URL of the generated video."
                }
              }
            }
          }
        }
      },

      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "Missing required parameter: 'model'."
              },
              "type": {
                "type": "string",
                "example": "invalid_request_error",
                "description": "Machine-readable error category."
              },
              "code": {
                "type": "string",
                "example": "invalid_request",
                "description": "Specific machine-readable error code."
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": "model",
                "description": "The request field that caused the error, or null."
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123",
                "description": "Unique request identifier for debugging and support."
              }
            }
          }
        }
      },

      "ModelNotFoundErrorResponse": {
        "type": "object",
        "description": "Returned when the specified video generation model does not exist or is not available.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "The model 'p-video-ultra' does not exist or is not available."
              },
              "type": {
                "type": "string",
                "example": "invalid_request_error"
              },
              "code": {
                "type": "string",
                "example": "model_not_found"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": "model"
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "InsufficientQuotaErrorResponse": {
        "type": "object",
        "description": "Returned when the account does not have enough credits to complete the request.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "Insufficient credits to process this request. Please recharge your account."
              },
              "type": {
                "type": "string",
                "example": "insufficient_quota"
              },
              "code": {
                "type": "string",
                "example": "insufficient_quota"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "RateLimitErrorResponse": {
        "type": "object",
        "description": "Returned when request rate limits are exceeded.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "Rate limit exceeded. Please try again later."
              },
              "type": {
                "type": "string",
                "example": "rate_limit_error"
              },
              "code": {
                "type": "string",
                "example": "rate_limit_exceeded"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "AuthenticationErrorResponse": {
        "type": "object",
        "description": "Returned when authentication fails.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "Missing authentication credentials."
              },
              "type": {
                "type": "string",
                "example": "authentication_error"
              },
              "code": {
                "type": "string",
                "example": "missing_api_key"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "PermissionErrorResponse": {
        "type": "object",
        "description": "Returned when the authenticated account does not have permission to access the resource.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "Permission denied: You do not have permission to access this model."
              },
              "type": {
                "type": "string",
                "example": "permission_error"
              },
              "code": {
                "type": "string",
                "example": "insufficient_quota"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "ServerErrorResponse": {
        "type": "object",
        "description": "Returned when an internal server error occurs.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "An unexpected error occurred while processing the request."
              },
              "type": {
                "type": "string",
                "example": "server_error"
              },
              "code": {
                "type": "string",
                "example": "internal_error"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "BackendUnavailableErrorResponse": {
        "type": "object",
        "description": "Returned when the upstream video provider is temporarily unavailable or could not be reached.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "The backend service is temporarily unavailable."
              },
              "type": {
                "type": "string",
                "example": "server_error"
              },
              "code": {
                "type": "string",
                "example": "backend_unavailable"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      },

      "VideoTimeoutErrorResponse": {
        "type": "object",
        "description": "Returned when a video generation job does not complete within the allowed polling window.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code", "request_id"],
            "properties": {
              "message": {
                "type": "string",
                "example": "Video generation timed out."
              },
              "type": {
                "type": "string",
                "example": "server_error"
              },
              "code": {
                "type": "string",
                "example": "backend_error"
              },
              "param": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "request_id": {
                "type": "string",
                "example": "req-qubrid-abc123"
              }
            }
          }
        }
      }
    }
  },

  "security": [
    {
      "BearerAuth": []
    }
  ],

  "paths": {
    "/videos/generations": {
      "post": {
        "summary": "Create Video",
        "description": "Generate a video using text, optional image input, optional audio input, or uploaded files.",
        "operationId": "createVideo",
        "tags": ["Videos"],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VideoGenerationRequest"
              },
              "examples": {
                "Text Only": {
                  "summary": "Generate a video from text only",
                  "value": {
                    "model": "p-video",
                    "prompt": "A butterfly flying through a flower garden",
                    "duration": 5,
                    "resolution": "720p",
                    "fps": 24,
                    "aspect_ratio": "16:9",
                    "draft": false,
                    "save_audio": true,
                    "prompt_upsampling": true
                  }
                },
                "Image + Audio URLs": {
                  "summary": "Generate a video using image and audio URLs",
                  "value": {
                    "model": "p-video",
                    "prompt": "A butterfly flying through a flower garden",
                    "duration": 5,
                    "resolution": "720p",
                    "fps": 24,
                    "aspect_ratio": "16:9",
                    "image": "https://example.com/input-image.jpg",
                    "audio": "https://example.com/audio.mp3",
                    "draft": false,
                    "save_audio": true,
                    "prompt_upsampling": true
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/VideoGenerationMultipartRequest"
              },
              "examples": {
                "File Upload": {
                  "summary": "Generate a video using uploaded image/audio files",
                  "value": {
                    "model": "p-video",
                    "prompt": "A butterfly flying through a flower garden",
                    "duration": "5",
                    "resolution": "720p",
                    "fps": "24",
                    "draft": "false",
                    "save_audio": "true",
                    "prompt_upsampling": "true"
                  }
                },
                "Multipart with URLs": {
                  "summary": "Use image/audio URLs via multipart form",
                  "value": {
                    "model": "p-video",
                    "prompt": "A butterfly flying through a flower garden",
                    "image": "https://example.com/input-image.jpg",
                    "audio": "https://example.com/audio.mp3",
                    "resolution": "720p",
                    "fps": "24",
                    "draft": "false",
                    "save_audio": "true",
                    "prompt_upsampling": "true"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Video generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VideoGenerationResponse"
                },
                "example": {
                  "created": 1710000000,
                  "data": [
                    {
                      "url": "https://cdn.qubrid.com/generated/video.mp4"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields, invalid values, or malformed input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits to process the request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsufficientQuotaErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - authenticated but not allowed to access this model or resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PermissionErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Model not found - the specified video model does not exist or is not available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelNotFoundErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServerErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Bad gateway - upstream video provider is unavailable or returned an error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackendUnavailableErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "Gateway timeout - video generation job did not complete in time",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VideoTimeoutErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}