Upload API_DOC.md

API_DOC.md

@@ -0,0 +1,208 @@
+# **API Documentation**
+
+This is the API documentation for the FastAPI application. The following endpoints are available:
+
+---
+
+### `POST /synthesize/`
+
+**Summary**: Synthesize
+
+- **Description**: This endpoint is used to generate synthesized output based on the provided text.
+
+- **Parameters**:
+  - **`text`** (query) **Required**: The text you want to synthesize (string).
+  - **`return_base64`** (query) **Optional**: Whether to return the result in base64 format. Default is `true` (boolean).
+  - **`diffusion_steps`** (query) **Optional**: Number of diffusion steps to perform. Minimum is 5, maximum is 200. Default is 5 (integer).
+  - **`embedding_scale`** (query) **Optional**: Scaling factor for embedding. Minimum is 1.0, maximum is 5.0. Default is 1.0 (number).
+
+- **Responses**:
+  - **Curl** (example):
+      ```curl
+      curl -X 'POST' \
+      'http://127.0.0.1:8000/synthesize/?text=StyleTTS%202%20is%20a%20text%20to%20speech%20model%20that%20leverages%20style%20diffusion%20and%20adversarial%20training%20with%20large%20speech%20language%20models%20to%20achieve%20human%20level%20text%20to%20speech%20synthesis.&return_base64=true&diffusion_steps=5&embedding_scale=1' \
+      -H 'accept: application/json' \
+      -d ''
+      ```
+  - **200 OK**: Successful Response
+    - Example Response (JSON):
+      ```json
+      {}
+      ```
+  - **422 Unprocessable Entity**: Validation Error
+    - Example Response (JSON):
+      ```json
+      {
+        "detail": [
+          {
+            "loc": ["query", "text"],
+            "msg": "field required",
+            "type": "value_error.missing"
+          }
+        ]
+      }
+      ```
+
+---
+
+### `POST /synthesize_longform_streaming/`
+
+**Summary**: Synthesize Longform
+
+- **Description**: This endpoint generates longform synthesized content based on the provided passage.
+
+- **Parameters**:
+  - **`passage`** (query) **Required**: The passage text to synthesize (string).
+  - **`return_base64`** (query) **Optional**: Whether to return the result in base64 format. Default is `false` (boolean).
+  - **`alpha`** (query) **Optional**: A scaling factor for the synthesis (number). Default is 0.7, minimum is 0.0, maximum is 1.0.
+  - **`diffusion_steps`** (query) **Optional**: Number of diffusion steps to perform. Minimum is 5, maximum is 200. Default is 10 (integer).
+  - **`embedding_scale`** (query) **Optional**: Scaling factor for embedding. Minimum is 1.0, maximum is 5.0. Default is 1.5 (number).
+
+- **Responses**:
+  - **Curl** (example):
+      ```curl
+      curl -X 'POST' \
+      'http://127.0.0.1:8000/synthesize_longform_streaming/?passage=%27%27%27If%20the%20supply%20of%20fruit%20is%20greater%20than%20the%20family%20needs%2C%20it%20may%20be%20made%20a%20source%20of%20income%20by%20sending%20the%20fresh%20fruit%20to%20the%20market%20if%20there%20is%20one%20near%20enough%2C%20or%20by%20preserving%2C%20canning%2C%20and%20making%20jelly%20for%20sale.%20To%20make%20such%20an%20enterprise%20a%20success%20the%20fruit%20and%20work%20must%20be%20first%20class.%20There%20is%20magic%20in%20the%20word%20%22Homemade%2C%22%20when%20the%20product%20appeals%20to%20the%20eye%20and%20the%20palate%3B%20but%20many%20careless%20and%20incompetent%20people%20have%20found%20to%20their%20sorrow%20that%20this%20word%20has%20not%20magic%20enough%20to%20float%20inferior%20goods%20on%20the%20market.%20As%20a%20rule%20large%20canning%20and%20preserving%20establishments%20are%20clean%20and%20have%20the%20best%20appliances%2C%20and%20they%20employ%20chemists%20and%20skilled%20labor.%20The%20home%20product%20must%20be%20very%20good%20to%20compete%20with%20the%20attractive%20goods%20that%20are%20sent%20out%20from%20such%20establishments.%20Yet%20for%20first-class%20homemade%20products%20there%20is%20a%20market%20in%20all%20large%20cities.%20All%20first-class%20grocers%20have%20customers%20who%20purchase%20such%20goods.%27%27%27&return_base64=false&alpha=0.7&diffusion_steps=10&embedding_scale=1.5' \
+      -H 'accept: application/json' \
+      -d ''
+      ```
+  - **200 OK**: Successful Response
+    - Example Response (JSON):
+      ```json
+      {}
+      ```
+  - **422 Unprocessable Entity**: Validation Error
+    - Example Response (JSON):
+      ```json
+      {
+        "detail": [
+          {
+            "loc": ["query", "passage"],
+            "msg": "field required",
+            "type": "value_error.missing"
+          }
+        ]
+      }
+      ```
+
+---
+
+### `POST /synthesize_with_emotion/`
+
+**Summary**: Synthesize With Emotion
+
+- **Description**: This endpoint allows the synthesis of content with emotional tone.
+
+- **Parameters**:
+  - **`return_base64`** (query) **Optional**: Whether to return the result in base64 format. Default is `true` (boolean).
+  - **`diffusion_steps`** (query) **Optional**: Number of diffusion steps to perform. Minimum is 5, maximum is 200. Default is 100 (integer).
+  - **`embedding_scale`** (query) **Optional**: Scaling factor for embedding. Minimum is 1.0, maximum is 5.0. Default is 5.0 (number).
+
+- **Request Body**:
+  - **Required**: A JSON object containing the texts to be synthesized.
+    - Example Request Body:
+      ```json
+      {
+        "texts": ["Text 1", "Text 2"]
+      }
+      ```
+
+- **Responses**:
+  - **200 OK**: Successful Response
+    - Example Response (JSON):
+      ```json
+      {}
+      ```
+  - **422 Unprocessable Entity**: Validation Error
+    - Example Response (JSON):
+      ```json
+      {
+        "detail": [
+          {
+            "loc": ["query", "return_base64"],
+            "msg": "value is not a boolean",
+            "type": "type_error.bool"
+          }
+        ]
+      }
+      ```
+
+---
+
+### `POST /synthesize_streaming_audio/`
+
+**Summary**: Synthesize Streaming Audio
+
+- **Description**: This endpoint generates streaming audio based on the provided text.
+
+- **Parameters**:
+  - **`text`** (query) **Required**: The text to synthesize into audio (string).
+  - **`return_base64`** (query) **Optional**: Whether to return the result in base64 format. Default is `false` (boolean).
+  - **`diffusion_steps`** (query) **Optional**: Number of diffusion steps to perform. Minimum is 5, maximum is 200. Default is 5 (integer).
+  - **`embedding_scale`** (query) **Optional**: Scaling factor for embedding. Minimum is 1.0, maximum is 5.0. Default is 1.0 (number).
+
+- **Responses**:
+  - **Curl** (example):
+      ```curl
+      curl -X 'POST' \
+        'http://127.0.0.1:8000/synthesize_with_emotion/?return_base64=true&diffusion_steps=100&embedding_scale=5' \
+        -H 'accept: application/json' \
+        -H 'Content-Type: application/json' \
+        -d '{"Happy": "We are happy to invite you to join us on a journey to the past, where we will visit the most amazing monuments ever built by human hands.",
+      "Sad": "I am sorry to say that we have suffered a severe setback in our efforts to restore prosperity and confidence.",
+      "Angry": "The field of astronomy is a joke! Its theories are based on flawed observations and biased interpretations!",
+      "Surprised": "I can'\''t believe it! You mean to tell me that you have discovered a new species of bacteria in this pond?"}'
+      ```
+  - **200 OK**: Successful Response
+    - Example Response (JSON):
+      ```json
+      {}
+      ```
+  - **422 Unprocessable Entity**: Validation Error
+    - Example Response (JSON):
+      ```json
+      {
+        "detail": [
+          {
+            "loc": ["query", "text"],
+            "msg": "field required",
+            "type": "value_error.missing"
+          }
+        ]
+      }
+      ```
+
+---
+
+## **Components**
+
+### **Schemas**
+
+#### `HTTPValidationError`
+
+- **Description**: Schema for validation errors in the API.
+- **Properties**:
+  - **`detail`**: List of validation errors (array of `ValidationError` objects).
+
+#### `ValidationError`
+
+- **Description**: Represents a single validation error.
+- **Properties**:
+  - **`loc`**: Location of the error (array of strings or integers).
+  - **`msg`**: Error message (string).
+  - **`type`**: Type of error (string).
+
+---
+
+### **Conclusion**
+
+This documentation provides a summary of the available API endpoints, parameters, responses, and error handling for the FastAPI application. Make sure to follow the guidelines for providing the correct parameters and formats when interacting with these endpoints.
+
+---
+
+### Notes:
+
+- **Default Values**: Default values for optional query parameters are listed in the descriptions.
+- **Error Handling**: All endpoints return a `422 Unprocessable Entity` error for validation failures with a detailed message.
+
+---