1. Real-time Control
FlightHub 2 OpenAPI V2.0 (On-Premises)
  • Call_Guide
    • Authentication Tutorial
    • Response Result
    • Request Structure
    • Error Codes
    • Public Parameters
  • Common
    • Common Foundation Tutorial
    • System Health & Access
      • DRC Service Health Check
    • Access and Authorization
      • STS Credentials
        • Get Business-Module Customized STS Credentials
        • Get Project-Level File Direct Upload STS Credentials
        • Get Flight Record Upload STS Credentials
    • Security
      • Decrypt Device Serial Number (SN) in Flight Record
  • Organization & Project
    • Organization and Project Tutorial
    • Project Management
      • Project Configuration
        • Get Project Auto Recording Configuration
        • Configure Project Auto Recording Rules
      • Project Basic Info
        • Create Project
        • Update Project Info
        • Get Project Details
        • Delete Project
      • Quick Join
        • Query Quick Join Project Info
        • Join Project via Quick Join Code
    • Organization Management
      • Query Organization Project List
      • Update Current User's Subscription Settings
      • Get Organization Details
      • Update Organization Info
    • Members & Permissions Management
      • Roles & Permissions
        • Get Project Permission Tree Definition
        • Query Project Role List Within Organization
        • Batch Create Project-Level Custom Roles
        • Query Role-Permission Mapping (Role ID → Permission List)
        • Delete Organization Custom Role
        • Update Custom Role
      • Organization Members
        • Batch Remove Organization Members
        • Query Organization Member List
        • Batch Add Organization Members
        • Batch Update Organization Member Info
        • Query Current User's Identity and Configuration in Organization
        • Update Current User's Organization Call Sign
        • Current User Exits Organization
      • Project Members
        • Get Project Team Members (Online)
        • Get Project User List
        • Update Current User's Project Call Sign
  • Device Management
    • Device Management Tutorial
    • Device Configuration
      • Device Shadow
        • Update Organization Device Shadow Configuration
        • Update Project Device Shadow Configuration
        • Query Organization Device Thing Model Attribute Current Values
      • Generic Configuration Command
        • Dispatch Custom Command to Organization Device (Generic cmds Channel)
        • Query Organization Device Command Execution Progress
        • Batch Query Organization Device Command Execution Progress
        • Dispatch Command to Devices in Project
      • HMS Event
        • Get Organization Device HMS Event List
        • Update Organization Device HMS Read Time
        • Update Project Device HMS Read Time
        • Batch Get Project Device HMS Events
      • Network Management
        • Query Device Current NTP Server Configuration
        • Start Device Network Speed Detection Task
        • Query Device Network Speed Test Task Result
        • Query Bay Network Configuration
        • Detect Bay Network Connection
        • Query 4G Module APN Configuration
      • RTK Configuration
        • Query Device's RTK Network Account Info
        • Custom Network RTK Calibration
      • Pairing Management
        • Query Device Pairing Info
        • Dispatch Device Pairing Command
        • Query Relay Scan Result
        • Query Relay Non-Paired Connection Result
        • Query Pairing Request Result
      • SIM Card Management
        • Query Device SIM Card Subscription and Data Info
      • Project Device Configuration
        • Modify Project Device Configuration Parameters
        • Get Project Device Configuration
    • Device List Management
      • Project Device List
        • Modify Organization Device's Current Workspace Project
        • Get Project Device List
        • Get Single Device Details Within Project
        • Modify Device Project Call Sign in Project
        • Get Project Historical Topology Device List
        • Get Project Device Thing Model
      • Organization Device List
        • Query Organization Device Simplified List
        • Batch Modify Organization Device Call Sign
        • Modify Single Organization Device Call Sign
        • Batch Remove Organization Devices
        • Query Organization Device O&M List
        • Query Model Primary Key List for a Device Category in Organization
        • Query Organization Device Online Working Quota
  • Real-time Control
    • Real-Time Control Tutorial
    • Flight Control Commands
      • Real-time Command
        • Query Project Device Command Execution Progress
        • Dispatch Flight Control Command
      • Airborne Task
        • Create Airborne-Dispatched Wayline Task
        • Control Wayline Task (Pause / Resume / Cancel)
      • Point-to-Fly
        • Get Flight Task Device Recommendation Result
        • Fly to Target Point (One-Click Takeoff)
        • Initiate Fly-to-Multiple-Targets Task
        • Update In-Progress Fly-to-Target Task
        • End Fly-to-Target Task
      • Smart Orbit
        • Enter POI Orbit Mode
        • Exit POI Orbit Mode
        • Update POI Orbit Speed
        • Query POI Task Status
      • Relay Task
        • Create Relay Task (Dual-Aircraft Rotation)
        • Calculate Best Relay Position for Relay Task
        • Edit Relay Task Configuration
        • Trigger Relay Aircraft Active Takeoff
        • Update Relay Task Running Status (Pause / Resume / Cancel)
        • Actively Switch Relay Task Executing Aircraft
    • Control Permission Management
      • Device Control Permission
        • Device Control Authority Operation (Organization Device O&M)
        • Query Device Control Authority Status (Organization Device O&M)
        • Acquire (Occupy) Cloud Control Role
        • Query Project Device Control Authority Status
        • Query User List in Project Recently Operating Device
        • Device Control Authority Operation
      • Cloud Control Permission
        • Request Cloud Control Authorization (Initiated to Remote Controller)
        • Batch Query Aircraft Cloud Control Authority Status
        • Acquire (Occupy) Cloud Control Permission
        • Release Cloud Control Permission
    • Payload Control
      • Camera Control
        • Dispatch Payload Control Command
      • PSDK Device
        • Dispatch PSDK Command
      • Speaker
        • Open Aircraft Two-Way Voice Channel
        • Open DRC Real-time Control Channel
        • Query Speaker Resource List
        • Create Speaker Resource
        • Delete Speaker Resource
        • Edit Speaker Resource
        • Get Speaker Audio Upload STS Credentials
    • Takeoff-Landing Coordination
      • Query TCA Real-time Status
  • Flight Task
    • Flight Tasks Tutorial
    • Task Query
      • Get Current Active Wayline Task (DRC Real-time Control)
      • Get Current Active Wayline Task (Task Management)
      • Batch Query Flight Task Details by UUID
      • Query Flight Task Time Conflict List
      • Get Flight Task Details (V2, includes execution details)
      • Query Dock Recent / Current Task
      • Get Task Flight Track (V2)
    • Flight Record
      • Export and Download
        • Flight Record File Download
        • Query Flight Task Export History
        • Export Flight Task Records (Generates Async ZIP Task)
        • Cancel / Delete Export Task
      • Operation Log
        • Query Flight Task Operation Log (V2)
    • Task Management
      • Create Flight Task
      • Create Flight Task (Advanced Version, Returns Subtasks)
      • Check Whether Flight Task Meets Dispatch Conditions
      • Mark Task as Read
      • Check Flight Task Block Items
      • Resumable Immediate Task
      • Delete Flight Task
      • Edit Flight Task
      • Get Flight Task Details
      • Dispatch Task Media Priority Upload Command
      • Create Resume Flight Task (Retain Original Breakpoint)
      • Update Flight Task Suspend Status (Suspend / Resume / Cancel)
      • Query Flight Task List
    • AI Flight Alert
      • Query Flight Sortie List with AI Alerts by Device SN
      • Query Historical AI Alert Records
  • Wayline
    • Waylines Tutorial
    • Download and Upload
      • Pack Resources to KMZ (Precise Recapture Flow)
      • Query Wayline Async Import Status
      • Wayline Save KMZ Upload Completion Callback
      • Wayline KMZ File Import Callback
      • Batch Download Waylines / Folders (ZIP Package)
    • Wayline List Management
      • Get Wayline KMZ Download URL and 302 Redirect
      • Copy Wayline
      • Favorite Wayline / Media Resource
      • Unfavorite Wayline / Media Resource
      • Stitch Multiple Waylines into One
      • Wayline Library File List Query (V1)
      • Delete Specified Wayline (default soft delete to recycle bin)
      • Update Wayline Metadata (Rename / Lock / Restore from Recycle Bin)
      • Get Single Wayline Details
    • Wayline File CRUD
      • Create Wayline Folder
      • Batch Delete Waylines / Folders
      • Batch Move Waylines / Folders to Target Folder
      • Move Wayline / Folder to Specified Group
      • Batch Update Wayline / Folder Lock Status
  • Map
    • Map Tutorial
    • Map Annotation
      • Annotation Layer Management
        • Move / Reorder Layers and Features
        • Delete Single Annotation Layer (Folder)
        • Update Annotation Layer (Rename / Reorder)
        • Distribute Annotation Layer to Device
        • Lock / Unlock Annotation Layer
        • Cancel Annotation Layer Distribution
        • Batch Delete Annotation Layers / Features
        • Create Annotation Layer (Folder)
        • Query Annotation Layer (Folder) List
      • Annotation Feature Management
        • Batch Modify Display Status of Features Under Layer
        • Clear All Annotation Features Under Specified Layer
        • Create Annotation Feature Under Specified Layer
        • Batch Import Layers and Annotations (KML-Style JSON)
        • Export Features Under Layer Group (KML-Style JSON)
        • Delete Single Annotation Feature
        • Update Annotation Feature (Rename / Modify Coordinates / Modify Style / Reorder)
      • Custom Icon
        • Query Project Custom Point Icon Library
        • Register Custom Point Icon
        • Delete Custom Point Icon
    • Signal Heatmap
      • Query Organization-Level Signal Heatmap
      • Query Project-Level Signal Heatmap
    • Airspace Safety
      • Custom Flight Area
        • Query Flight Area List Under Project
        • Create Flight Area
        • Trigger Flight Area Configuration Sync to Device
        • Delete Flight Area
        • Update Flight Area
    • Offline Map
      • Get Offline Map Terrain Model Download URL
      • Trigger Offline Map Package Sync to Bay
      • Get Project Offline Map Details
      • Configure Project Offline Map Manifest (Start New Update)
      • Cancel Offline Map Model Update
  • Livestream
    • Live Streaming Tutorial
    • Livestream Sharing & Forwarding
      • Bypass Streaming
        • Query Current Organization Bypass Transcoder List
        • Create / Enable / Disable / Update Stream Forwarder
        • Stop and Delete Specified Bypass Transcoder (C2C Livestream Bypass)
      • Livestream Sharing
        • Get Device Livestream Share Details
        • Query All Livestream Share Links Under Project
    • Livestream Push
      • Project Level
        • Start Livestream (Project Level)
        • Update Viewer Tokens (Project Level)
        • Switch Camera (Project Level)
        • Switch Livestream Camera (Project Level)
        • Report Viewer Join Livestream Room Status (Project Level)
        • Stop Livestream (Project Level)
        • Set Livestream Quality (Project Level, aircraft source-side push level)
        • Query Device Livestream and Recording Status (Project Level)
      • Organization Level
        • Stop Livestream (Organization Level)
        • Set Livestream Quality (Organization Level, aircraft source-side push level)
        • Report Viewer Join Livestream Room Status (Organization Level)
        • Start Livestream (Organization Level)
        • Switch Camera (Organization Level, also controls aircraft source-side hardware)
        • Update Viewer Tokens (Organization Level)
        • Switch Livestream Camera (Organization Level)
    • Recording Task Management
      • Start Cloud Recording (Project Level)
      • Stop Cloud Recording (Project Level)
      • Query Device Recording Task List (Project Level)
      • Start Intra-Project Livestream
      • Query Device Recording Task List (Organization Level)
      • Start Cloud Recording (Organization Level)
      • Stop Cloud Recording (Organization Level)
      • Stop Intra-Project Livestream Recording
  • Media
    • Media Tutorial
    • Flight Task Association
      • Query Flight Task Media by flight_id
      • Batch Query Flight Media by flight_ids
    • File Statistics and Query
      • Get Media File Count (by Folder Granularity)
      • Get Total Media File Count (Project-Wide)
      • Get Media Resource Files (Images + Folders)
    • Media File CRUD
      • Batch Set Media Map Display Status
      • Batch Delete Media Files - to Recycle Bin
      • Create Media Folder
      • Get Media File List
      • Media File Cropping
      • Batch Move Media Files
      • Delete Single Media File
      • Get Media File Details
      • Update Media File Info
      • Batch Hard Delete Media Files - Not to Recycle Bin
    • Download and Upload
      • Quick Upload Media File
      • Import Media File
      • Check New File Fingerprint Existence Status
      • Annotation Callback
      • Media Upload Completion Callback
      • Check ZIP Package Task Status
      • Package Media Files into ZIP
      • Get Media File Download URL
    • Tag Management
      • Add Tag to Media File
      • Delete Media File Tag
      • Get Media File Tag List Under Project
  • Model
    • Models Tutorial
    • Model Reconstruction
      • Geographic Systems
      • Get Flight Task Folder List V2
      • Get Real-time Mapping Task List
      • Initiate Real-time Mapping Task (Realtime2D)
      • Get Project Model Library Default Settings
      • Initiate Post-Processing Reconstruction Task (Post 2D / 3D)
      • Get Post-Reconstruction Default ROI
      • Get Post-Reconstruction Quality Report Download Link
      • Post-Reconstruction Task Retry
      • Stop Post-Reconstruction Task
      • Model Upload Completion Callback (called by client, not OSS signature verification)
      • Query Wayline List Available for Model Reconstruction
    • Model Library
      • Model File Management
        • Batch Delete Model Files
        • Get Project Model File List
        • Create Model Folder
        • Batch Toggle Model Map Display Status
        • Lock / Unlock Model File
        • Batch Move Model Files
        • Intra-Org Model Sharing
        • Get Total Model File Count
        • Delete Single Model File
        • Get Model File Details
        • Update Model Basic Info
        • Get Model File Download URL
        • Initiate Model Format / Coordinate System Conversion Task
        • Get Available Coordinate System (WKT) List for Project
      • Map Display
        • Batch Set Terrain Loading Status of Real-time Mapping Models
        • Adjust Display Order of Real-time Mapping Models (Drag-and-Drop Sort)
        • Update Mapping Task Metadata (Rename / Show-Hide / Distribute / Undistribute / Toggle Terrain)
        • Get Map Page Model Layer List
        • Batch Toggle Map Model Layer Attributes
        • Adjust Map Model Layer Stacking Order
  • Recycle Bin
    • Recycle Bin Tutorial
    • Hard Delete Single Media File
    • Restore File from Recycle Bin
    • Permanently Delete Recycle Bin Files
    • Get Media Recycle Bin File List
    • Modify Media Recycle Bin Configuration
    • Get Media Recycle Bin Configuration
    • Get Model Library Recycle Bin Disk Statistics
    • Get Media Recycle Bin Disk Statistics
  • Advanced Capabilities
    • Advanced Capabilities Tutorial
    • Change Detection
      • Media Change Detection
        • Initiate Media Spot-the-Difference Task
        • Query Media Spot-the-Difference Task List
        • Delete Spot-the-Difference Task
        • Modify Spot-the-Difference Task Name and Other Attributes
        • Get Spot-the-Difference Task Details
        • Evaluate Spot-the-Difference Task
        • Batch Modify Spot-the-Difference Result Status
        • Delete Change Area
        • Add Change Area (Manual Annotation)
        • Update Change Area Attributes
        • Get Media Upload STS Credentials
        • Media Spot-the-Difference Task Pre-check
        • View Spot-the-Difference Detection Report
        • Get Photo Group AI Spot-the-Difference Result List
        • Get Change Area Details in Result Group
      • Model Change Detection
        • Initiate Model Comparison Task (Spot-the-Difference)
        • Query Model Comparison Task List
        • Modify Model Comparison Task Name and Other Attributes
        • Get Model Comparison Task Result Details
        • Delete Model Comparison Task
        • Batch Update Model Comparison Diff
        • Delete Model Comparison Diff
        • Add Model Comparison Diff (Manual Annotation)
        • Update Single Model Comparison Diff Details
        • Get Model Comparison Detection Report
        • Query Candidate Models Suitable for Model Comparison
        • Evaluate Model Comparison Task
  • Open Modeling
    • Reconstruction Algorithm Description
    • Error_Codes.md
    • Feature Introduction
    • Update Date: 2026-05-07
    • Get In-Progress Reconstruction Model Details
    • Get Resource Details
    • Delete Resource
    • Get Upload Credentials
    • Start Reconstruction Task
    • Upload Callback
    • Stop Reconstruction Task
    • Get Model Details
    • Delete Model
  • Schemas
    • Default Directory
      • StsCredentials
      • PutWorkspacesWaylinesBatchDeleteResp
      • PutWorkspacesWaylinesLockStatusResp
      • C0160_GetFlightTaskAdvanced_Resp
      • C0617_GetFlightTasks_Resp
      • StsResult
      • C0619_CreateBatchDownload_Resp
      • GetWorkspacesFilesCompareFilesResp
      • ProjectTeamGetDevicesRsp
      • PostWorkspacesStsResp
      • Resp
      • ApiEnvelope
      • ServiceError
      • PagyInfo
      • GetDiffMediaTaskIdGetReportResp
      • GetWorkspacesByWorkspaceIdComparatorsByTaskUuidResultGroupsResp
      • GetWorkspacesByWorkspaceIdComparatorsByTaskUuidResultGroupsByResultUuidResp
      • PostWorkspacesComparatorsResultGroupsDiffDetailResp
      • DeleteWorkspacesComparatorsResultGroupsDiffDetailResp
      • GetDiffModelTaskIdGetResultResp
      • PostWorkspacesComparatorsDiffDetailResp
      • DeleteWorkspacesComparatorsDiffDetailResp
      • GetDiffModelTaskIdGetReportResp
      • GetWorkspacesComparatorsMatchImageResp
      • ApiPagedEnvelope
      • InitPermissionTreeNode
      • PutWorkspacesWaylineMoveResp
      • DeleteWorkspacesWaylinesByIdResp
      • PostWorkspacesWaylinesConcatResp
      • C0148_ExportRecords_Resp
      • C0362_GetWaylineImportState_Resp
      • ProjectTeamGetDevicesRspItem
      • ProjectTeamGetDevicesRspItemBaseTopo
      • DeviceModelEnum
      • Position
      • DeviceState_ea210dock
      • DeviceState_ea220dock
      • DeviceState_ea230dock
      • DeviceState_ea210drone
      • DeviceState_ea220drone
      • DeviceState_ea230drone
      • DeviceState_wm265
      • DeviceState_wa345
      • DeviceState_drone_other
      • DeviceState_rc_other
      • DeviceState_rc510
      • DeviceState_rc701
  1. Real-time Control

Real-Time Control Tutorial

Feature Introduction#

The Real-Time Control module covers all capabilities of "real-time cloud user operations on devices" in FlightHub 2 On-Premises version, divided into five major sections:
Control Authority Management: Application, occupation, release, preemption, and transfer of flight control authority / payload control authority; provides both cloud_controls path and DRC role path.
Flight Control Commands
Real-time Commands: Dispatch flight control commands (pass-through device thing model) + command progress query.
Fly-to Point: Device recommendation → one-click takeoff → multi-target point fly-to → dynamic adjustment / end.
Smart Orbit (POI): Enter / exit POI mode, dynamically change speed, query task status.
Relay Mission: Dual-drone rotation mission creation, optimal relay position calculation, status control, active takeoff, active switching.
In-flight Task: In-flight dispatch of new wayline, pause / continue / cancel wayline task.
Payload Control: Camera / gimbal / PSDK / megaphone (including resource management + STS).
Takeoff and Landing Coordination: TCA real-time status query.
Control authority precondition: For all interfaces that actually dispatch device commands such as "flight control", "payload control", "fly-to point", "POI", "relay mission", etc., the caller must first hold the corresponding control authority (flight / payload_{index}) of the target drone; otherwise, errors of type 228430 / 228431 will be returned.
DRC vs Topologies: There are two paths for device command channels at the project dimension — topologies/cmds (device O&M / general commands) and drc/api (DRC real-time control / control authority / duplex channel). Do not mix them.
Asynchronous channel: All "command dispatch" interfaces immediately return asynchronous identifiers such as tid; the real result is obtained through the command progress query interface or WebSocket push. Do not assume synchronous completion.

Interface Usage Flow#

Control Authority Management#

Control authority is the "admission ticket" for all real-time control interfaces. The On-Premises version provides two semantically equivalent path sets:
Path FormApplicable Scenario
/projects/{uuid}/topologies/cmds/control (Project Dimension)Project operator collaborative operation (apply / approve / reject / release)
/projects/{uuid}/drc/roles (DRC Role)Directly occupy "cloud control role"
/drc/api/v1/projects/{uuid}/cloud_controlsDirectly occupy / release cloud control authority, at control_keys granularity
/organizations/{uuid}/manage-devices/cmds/control (Organization O&M)O&M administrator's control authority operation on organization devices
Call steps:
1.
Query: Batch Query Drone Cloud Control Authority Status (GET /openapi/v2.0/drc/api/v1/projects/{uuid}/cloud_controls), batch query by SN list (up to 50 SNs per call).
2.
Occupy: Get (Occupy) Cloud Control Authority (POST /openapi/v2.0/drc/api/v1/projects/{uuid}/cloud_controls). The request body uses drone_sn (drone SN) + control_keys (list of control authority keys); the key pattern is flight or payload_{payload index} (e.g. payload_53-0-0, the index format is consistent with the device thing model camera field). No remote controller approval required.
3.
Release: Release Cloud Control Authority (DELETE /openapi/v2.0/drc/api/v1/projects/{uuid}/cloud_controls).
4.
Cross-end collaboration: For the "apply—approve—release" workflow (with remote controller side confirmation), use instead:
Apply for Cloud Control Authorization (Initiate to Remote Controller) (POST /openapi/v2.0/drc/api/v1/projects/{uuid}/cloud_control_auth): Immediately returns bid; the result is pushed via device-side asynchronous callback.
Device Control Authority Operation (POST /openapi/v2.0/manage/api/v1/projects/{uuid}/topologies/cmds/control): 6 actions (apply / preempt queue / cancel / approve / reject / release).
Query Project Device Control Authority Status (GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/cmds/control/status).
Query List of Project Users Recently Operating the Device (GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/cmds/operation-users) — Dashboard / collaborative view to query active operators of multiple devices.
Corresponding for organization O&M scenarios: POST /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/control + GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/control/status.
5.
DRC role: Get (Occupy) Cloud Control Role (POST /openapi/v2.0/manage/api/v1/projects/{uuid}/drc/roles) — Used to occupy flight_control / payload_control roles. After successful occupation, all relevant users immediately receive WebSocket real-time change notifications.

Flight Control Commands — Real-time Commands#

Call steps:
1.
Call Dispatch Flight Control Command (POST /openapi/v2.0/manage/api/v1/projects/{uuid}/flight-commands); pass device_sn (required), device_cmd_method (required, command name), device_cmd_data (optional, command parameter object) in the body. The specific device_cmd_method name and device_cmd_data structure of the command are determined by the drone model thing model, subject to the drone SDK documentation; the server pass-through does not perform enum verification.
2.
Query progress: Query Project Device Command Execution Progress (GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/cmds). The organization-dimension batch progress query interface (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds) is currently classified under the "Device Management" module in spec; see Device Management Tutorial for details.

Flight Control Commands — Fly-to Point (FlyTo)#

Call steps:
1.
Device recommendation: Get Flight Task Device Recommendation Result (POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/device-recommendation), reverse-derive available "dock + drone" combinations by business scenario (8 strategy categories including fly-to point / regular wayline takeoff / frog-jump wayline / dual-drone relay / base station recommendation / emergency response, etc.) + start / end positions.
2.
Occupy control authority: See Control Authority Management above.
3.
One-click takeoff + fly to single point: Fly to Target Point (One-click Takeoff) (POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/drone-take-off). Common fields in the request body: device_sn, target_latitude, target_longitude, target_height, takeoff_mode, security_takeoff_height, max_speed, out_of_control_action, rth_altitude, media_folder_name, etc. (specific fields subject to the spec interface definition); returns flight_id / fly_to_id.
4.
Fly to multiple target points: Initiate Fly to Multiple Target Points Task (POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/fly-to-points) — Aimed at multi-point trajectory planning for drones that have already taken off; request body fields: device_sn, start_point, points, max_speed.
5.
Dynamic adjustment: Update Ongoing Fly to Target Point Task (PUT /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/fly-to-points) — The drone continues to fly according to the new sequence when switching to the next waypoint; no need to stop and re-dispatch.
6.
Active end: End Fly to Target Point Task (DELETE /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/fly-to-points) — The drone stops going to the remaining waypoints; the device side handles the follow-up according to the out-of-control action set when dispatching the "one-click takeoff" task.

Flight Control Commands — Smart Orbit (POI)#

Call steps:
1.
Enter POI: Enter POI Orbit Mode (POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/poi-enter); request body required device_sn + poi_center_point.{latitude, longitude, height}; optional payload_index (bind gimbal payload), speed (orbit speed), circle_radius (orbit radius).
2.
Speed adjustment: Update POI Orbit Speed (PUT /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/poi-speed).
3.
Query: Query POI Task Status (GET /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/poi-task) — Used for client panel refresh or disconnection reconnection recovery.
4.
Exit: Exit POI Orbit Mode (DELETE /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/poi-exit).

Flight Control Commands — Relay Mission (Dual-drone Rotation)#

Call steps:
1.
Calculate relay point: Calculate Best Relay Position for Relay Mission (POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/relay-missions/positions) — Calculate "relay point" coordinates and relay operation radius based on operating drone dock position + relay drone current position + RTK calibration status.
2.
Create mission: Create Relay Mission (Dual-drone Rotation) (POST /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/flight-tasks/relay-missions). Request body required fields (per spec): main_drone_sn, secondary_drone_sn, mission_position, end_at, out_of_control_action, main_rth_altitude, secondary_rth_altitude, early_departure_time, flight_id, uniformly orchestrated by the dispatch center according to field configuration.
3.
Executable during mission runtime:
Actively take off relay drone: Trigger Active Takeoff of Relay Drone (POST /flight-tasks/relay-missions/{relay_mission_id}/active-takeoff) — By default, the relay drone is automatically taken off by the dispatch center according to early_departure_time (advance departure time) and the main operating drone battery; this interface provides manual trigger capability.
Edit configuration: Edit Relay Mission Configuration (PUT /flight-tasks/relay-missions/{relay_mission_id}) — Can modify deadline / out-of-control action / respective return altitude / speed, etc., without rebuilding the mission.
Status control: Update Relay Mission Running Status (Pause / Resume / Cancel) (PUT /flight-tasks/relay-missions/{relay_mission_id}/status). paused can only be paused when running; will send commands to stop fly-to point flight for main and secondary drones that are flying and not in return / landing.
Active switching: Actively Switch Execution Drone of Relay Mission (PUT /flight-tasks/relay-missions/{relay_mission_id}/switch) — Before calling, the relay drone must have flown to the relay point and be in position; switching will recalculate the relay point and register a new mission with the dispatch center.

Flight Control Commands — In-flight Dispatch Wayline#

Call steps:
1.
During the drone's in-flight execution of a mission, temporarily switch wayline: Create In-flight Dispatch Wayline Task (POST /openapi/v2.0/drc/api/v2/projects/{project_id}/flight-tasks/in-flight-way-line-task); no need to have the drone return and take off again first.
2.
Midway control: Control Wayline Task (Pause / Continue / Cancel) (PUT /openapi/v2.0/drc/api/v2/projects/{uuid}/flight-wayline-tasks/commands).

Payload Control — Camera / PSDK#

InterfacePurpose
POST /openapi/v2.0/manage/api/v1/projects/{uuid}/payload-commandsDispatch payload control commands (gimbal pitch / photo / video / zoom, etc.)
POST /openapi/v2.0/manage/api/v1/projects/{uuid}/psdk/commandsDispatch PSDK commands (pass-through channel)
The request body structures of the two interfaces are consistent: both use device_sn + device_cmd_method (command name) + device_cmd_data (command parameter object, determined by the device / PSDK thing model); the server does not perform enum verification, serving as a pass-through channel overall.
Before calling, the corresponding payload control authority of the drone (payload_{payload index}) must be held; otherwise, it will be rejected by the server (error code 228431).
"Lens switching / camera switching" during live streaming does not go through this set of interfaces: Live streaming-related lens switching interfaces (such as change-lens / change-camera) are located in the "Live Streaming" module; see Live Streaming Tutorial for details.

Payload Control — Megaphone#

The megaphone is divided into two lines: real-time bidirectional voice channel + megaphone resource (audio file / TTS) library.
Call steps:
1.
Real-time bidirectional voice: Open Drone Bidirectional Voice Channel (POST /openapi/v2.0/drc/api/v2/projects/{uuid}/voice-channels/{sn}). The server will select and initialize the RTC service provider (Agora / Volcano Engine / Twilio, etc.); the response's data.voice_channel.{provider, config} carries the RTC access parameters (provider determines the SDK used by the front-end, config contains specific parameters such as room ID / Token / UID).
2.
DRC real-time control channel: Open DRC Real-time Control Channel (POST /openapi/v2.0/drc/api/v2/projects/{project_id}/rt-channels/{sn}). The response simultaneously returns data.rt_channel and data.data_channel, which are equivalent configurations; choose either based on client implementation needs.
3.
Megaphone resources — Upload:
Get STS: Get Megaphone Audio Upload STS Credentials (GET /openapi/v2.0/speaker/api/v1/workspaces/{workspace_id}/sts).
After direct upload to object storage, call Create Megaphone Resource (POST /openapi/v2.0/speaker/api/v1/workspaces/{workspace_id}/resources) to register. file_type=audio submits object_key; file_type=tts submits text, asynchronously synthesized + transcoded by the server.
Two-stage recording (create_scene=record): First create a placeholder with visible=false; after recording is complete, set visible to true via Edit Megaphone Resource (PUT /openapi/v2.0/speaker/api/v1/workspaces/{workspace_id}/resources/{id}).
4.
Megaphone resources — Query / Delete:
Query Megaphone Resource List (GET /openapi/v2.0/speaker/api/v1/workspaces/{workspace_id}/resources) — Only returns resources with visible=true and not soft-deleted; audio comes with a signed object_url for direct preview / download, in descending order by created_at.
Delete Megaphone Resource (DELETE /openapi/v2.0/speaker/api/v1/workspaces/{workspace_id}/resources/{id}) — Soft delete; object storage files are asynchronously cleaned up by the background.

Takeoff and Landing Coordination (TCA)#

Query Takeoff and Landing Coordination Area (TCA) Real-time Status (GET /openapi/v2.0/task/api/v1/workspaces/{workspace_id}/groups/tcas) is used for priority avoidance of multi-drone same-site takeoff and landing — a TCA is composed of several docks in the same area; when any dock in the area takes off or lands, the entire TCA enters the occupied state, avoiding conflicts caused by other docks taking off / landing simultaneously. This interface can be queried before creating an immediate task to confirm whether the airspace is available.

Typical Scenario: Complete FlyTo Chain (V2.0 Path)#

Semantically consistent with the V0.9 On-Premises "FlyTo API Call Guide", paths have been adapted to V2.0.
For details on flight task detail query and media file list, see Flight Tasks Tutorial and Media Tutorial.
Modified at 2026-06-15 14:35:50
Previous
Query Organization Device Online Working Quota
Next
Query Project Device Command Execution Progress
Built with