diff --git a/api/@ohos.floatingBall.d.ts b/api/@ohos.floatingBall.d.ts
new file mode 100644
index 0000000000000000000000000000000000000000..91a73f2babb33ab9752c0bfc58a12597ca882462
--- /dev/null
+++ b/api/@ohos.floatingBall.d.ts
@@ -0,0 +1,330 @@
+/*
+ * Copyright (c) 2025 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file
+ * @kit ArkUI
+ */
+
+import type BaseContext from './application/BaseContext';
+import type image from './@ohos.multimedia.image';
+import type Want from './@ohos.app.ability.Want';
+import type { Callback } from './@ohos.base';
+
+/**
+ * Floating-ball
+ *
+ * @namespace floatingBall
+ * @syscap SystemCapability.Window.SessionManager
+ * @since 20
+ */
+declare namespace floatingBall {
+  /**
+   * If floating-ball enabled in current OS.
+   *
+   * @returns { boolean } true if floating-ball enabled, otherwise false.
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  function isFloatingBallEnabled(): boolean;
+
+  /**
+   * Create floating-ball controller
+   *
+   * @param { FloatingBallConfiguration } config - Params for floating-ball controller creation. 
+   * The config must be valid, the context in config should not be null. 
+   * @returns { Promise<FloatingBallController> } - The promise returned by the function.
+   * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities.
+   * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating-ball.
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  function create(config: FloatingBallConfiguration): Promise<FloatingBallController>;
+
+  /**
+   * FloatingBallConfiguration
+   *
+   * @interface FloatingBallConfiguration
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  interface FloatingBallConfiguration {
+    /**
+     * Indicates window context.
+     *
+     * @type { BaseContext }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    context: BaseContext;
+  }
+
+  /**
+   * FloatingBallController
+   *
+   * @interface FloatingBallController
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  interface FloatingBallController {
+    /**
+     * Start floating-ball
+     * 
+     * @permission ohos.permission.USE_FLOAT_BALL
+     * @param { FloatingBallParams } params - Params for floating-ball start.
+     * @returns { Promise<void> } - The promise returned by the function.
+     * @throws { BusinessError } 201 - Permission verification failed, usually returned by VerifyAccessToken.
+     * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating-ball.
+     * @throws { BusinessError } 1300020 - Failed to create the floating-Ball window.
+     * @throws { BusinessError } 1300021 - Failed to start multiple floating-Ball window.
+     * @throws { BusinessError } 1300022 - Repeated floating-Ball operation.
+     * @throws { BusinessError } 1300023 - Floating-ball internal error.
+     * @throws { BusinessError } 1300024 - The floating-ball window state is abnormal.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    startFloatingBall(params: FloatingBallParams): Promise<void>;
+
+    /**
+     * Update floating-ball
+     * 
+     * @param { FloatingBallParams } params - Params for floating-ball update. 
+     * @returns { Promise<void> } - The promise returned by the function.
+     * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating-ball.
+     * @throws { BusinessError } 1300023 - Floating-ball internal error.
+     * @throws { BusinessError } 1300024 - The floating-ball window state is abnormal.
+     * @throws { BusinessError } 1300025 - The floating-ball state does not support this operation.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    updateFloatingBall(params: FloatingBallParams): Promise<void>;
+
+    /**
+     * Stop floating-ball.
+     * 
+     * @returns { Promise<void> } - The promise returned by the function.
+     * @throws { BusinessError } 1300022 - Repeated floating-Ball operation.
+     * @throws { BusinessError } 1300023 - Floating-ball internal error.
+     * @throws { BusinessError } 1300024 - The floating-ball window state is abnormal.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    stopFloatingBall(): Promise<void>;
+
+    /**
+     * Register floating-ball lifecycle event listener.
+     * 
+     * @param { 'stateChange' } type - Registration type, floating-ball lifecycle state change, 'stateChange'.
+     * @param { Callback<FloatingBallState> } callback - Used to handle {'stateChange'} command.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    on(type: 'stateChange', callback: Callback<FloatingBallState>): void;
+
+    /**
+     * Unregister floating-ball lifecycle event listener.
+     * 
+     * @param { 'stateChange' } type - Used to unregister listener for {'stateChange'} command.
+     * @param { Callback<FloatingBallState> } [callback] - Indicates the callback function.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    off(type: 'stateChange', callback?: Callback<FloatingBallState>): void;
+
+    /**
+     * Register floating-ball click event listener.
+     * 
+     * @param { 'clickEvent' } type - Registration type, user click event, 'clickEvent'.
+     * @param { Callback<void> } callback - Used to handle {'clickEvent'} command.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    on(type: 'clickEvent', callback: Callback<void>): void;
+
+    /**
+     * Unregister floating-ball click event listener.
+     * 
+     * @param { 'clickEvent' } type - Used to unregister listener for {'clickEvent'} command.
+     * @param { Callback<void> } [callback] - Indicates the callback function.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    off(type: 'clickEvent', callback?: Callback<void>): void;
+
+    /**
+     * Get the info of floating-ball window.
+     * 
+     * @returns { Promise<FloatingBallWindowInfo> } - The promise used to return the floating-ball window info.
+     * @throws { BusinessError } 1300023 - Floating-ball internal error.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    getFloatingBallWindowInfo(): Promise<FloatingBallWindowInfo>;
+
+    /**
+     * Restore main window for floating-ball creatorBundle.
+     *
+     * @param { Want } want - Params for floating-ball restoration.
+     * @returns { Promise<void> } - The promise returned by the function.
+     * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating-ball.
+     * @throws { BusinessError } 1300023 - Floating-ball internal error.
+     * @throws { BusinessError } 1300025 - The floating-ball state does not support this operation.
+     * @throws { BusinessError } 1300026 - Failed to restore the main window.
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    restoreMainWindow(want: Want): Promise<void>;
+  }
+
+  /**
+   * The option of floating-ball
+   *
+   * @interface FloatingBallParams
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  interface FloatingBallParams {
+    /**
+     * The template of floating-ball.
+     *
+     * @type { FloatingBallTemplate }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    template: FloatingBallTemplate;
+    
+    /**
+     * The title of floating-ball.
+     *
+     * @type { string }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    title: string;
+    
+    /**
+     * The content of floating-ball.
+     *
+     * @type { ?string }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    content?: string;
+    
+    /**
+     * The backgroundColor of floating-ball.
+     *
+     * @type { ?string }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    backgroundColor?: string;
+    
+    /**
+     * The icon of floating-ball.
+     *
+     * @type { ?image.PixelMap }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    icon?: image.PixelMap;
+  }
+
+  /**
+   * Enum for FloatingBall state type.
+   *
+   * @enum { number }
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  enum FloatingBallState {
+    /**
+     * FloatingBall window started.
+     *
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    STARTED = 1,
+  
+    /**
+     * FloatingBall window stopped.
+     *
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    STOPPED = 2,
+  }
+
+  /**
+   * Enum for FloatingBall template type.
+   *
+   * @enum { number }
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  enum FloatingBallTemplate {
+    /**
+     * Static layout, support icon and title.
+     *
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    STATIC = 1,
+  
+    /**
+     * Normal layout, support title and content with different color.
+     *
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    NORMAL = 2,
+  
+    /**
+     * Emphatic layout, support title and content with different size.
+     *
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    EMPHATIC = 3,
+  
+    /**
+     * Simple layout, support title with 2-lines display.
+     *
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    SIMPLE = 4,
+  }
+
+  /**
+   * The info of floating-ball window.
+   *
+   * @interface FloatingBallWindowInfo
+   * @syscap SystemCapability.Window.SessionManager
+   * @since 20
+   */
+  interface FloatingBallWindowInfo {
+    /**
+     * Indicates target window id.
+     *
+     * @type { number }
+     * @syscap SystemCapability.Window.SessionManager
+     * @since 20
+     */
+    windowId: number;
+  }
+}
+
+export default floatingBall;
diff --git a/kits/@kit.ArkUI.d.ts b/kits/@kit.ArkUI.d.ts
index 2b8d6720b5c8af74206b1d9f61e59df7445c5306..6020791908bf965c5cc7ba84b8b8f095fa562017 100644
--- a/kits/@kit.ArkUI.d.ts
+++ b/kits/@kit.ArkUI.d.ts
@@ -126,6 +126,7 @@ import matrix4 from '@ohos.matrix4';
 import MeasureText, { MeasureOptions } from '@ohos.measure';
 import mediaquery from '@ohos.mediaquery';
 import PiPWindow from '@ohos.PiPWindow';
+import floatingBall from '@ohos.floatingBall';
 import pluginComponentManager, { PluginComponentTemplate } from '@ohos.pluginComponent';
 import prompt from '@ohos.prompt';
 import promptAction, { LevelMode, ImmersiveMode, LevelOrder } from '@ohos.promptAction';
@@ -247,7 +248,7 @@ export {
   InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset,
   LabelOptions, LayeredDrawableDescriptor, LoadingDialog, LocaleResponse, MarginType, Matrix4, MeasureOptions, MeasureText,
   MediaQuery, MediaQueryEvent, MediaQueryList, NodeController, NodeParam, NodeRenderType, Offset, OperateButton, OperateCheck, OperateIcon,
-  OperateItem, OperationOption, OperationType, OverlayManager, PathShape, PiPWindow, Pivot, Popup, PopupButtonOptions, PopupIconOptions, PopupOptions,
+  OperateItem, OperationOption, OperationType, OverlayManager, PathShape, PiPWindow, floatingBall, Pivot, Popup, PopupButtonOptions, PopupIconOptions, PopupOptions,
   PopupTextOptions, Position, PrefixIconOptions, ProgressButton, ProgressButtonV2, ProgressButtonV2Color, ProgressButtonV2ColorOptions, Prompt, PromptAction, PromptOptions, RectShape, RenderNode, RenderOptions, BuildOptions,
   RequestFullWindowOptions, Rotation, Router, RouterOptions, RouterState, Scale, ScreenOnVisibleOptions, SegmentButton, SegmentButtonItemOptionsArray,
   SegmentButtonOptions, SelectDialog, SelectOptions, SelectTitleBar, SelectTitleBarMenuItem, SelectionMenu,