Detailed Parameters

Version History

Create a live stream

Creates an editing live stream. Once created, the live stream enters a waiting state; you then need to establish the WebSocket connection and join RTC before going live.

Request example

curl -X POST "https://api.vidu.cn/live/s_editing/realtime" \
  -H "Authorization: vda_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/reference.png",
    "editing_type": "style_transfer",
    "rtmp_urls": ["rtmp://push.example.com/live/stream1"]
  }'

Response example

{
  "live": {
    "id": "995200676634042368",
    "live_duration": 120,
    "status": "waiting",
    "call_mode": "video",
    "created_at": "1789025863",
    "trace_id": "d17ab29172bef09b3f093b169c233e67"
  },
  "rtc": {
    "app_id": "xxx",
    "channel_id": "xxx",
    "user_id": "xxx",
    "token": "xxx",
    "token_expire_at": "1789033063"
  },
  "render_uid": "xxx"
}

Request headers

Request parameters Two RTC access modes are supported: When rtc_info is omitted, the platform creates and manages the RTC channel (Alibaba Cloud RTC by default, provider=artc), and the response returns the join credentials rtc and the edited-result stream UID render_uid. When rtc_info is provided, the platform no longer creates a channel and connects directly to your own RTC channel instead; in that case rtc and render_uid in the response are empty. See "Publishing and subscribing" for details.

customer_rtc object fields

provider enum values

managed_rtc object fields

curl -X POST "https://api.vidu.cn/live/s_editing/realtime" \
  -H "Authorization: vda_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/reference.png",
    "editing_type": "style_transfer",
    "managed_rtc": { "provider": "trtc" }
  }'

Response example

{
  "live": { "id": "1234567890", "status": "waiting" },
  "client_secret": "<client_secret>",
  "rtc": {
    "app_id": "<app_id>",
    "channel_id": "<channel_id>",
    "user_id": "<user_id>",
    "token": "<token>",
    "token_expire_at": "1790000000",
    "provider": "trtc"
  },
  "render_uid": "<render_uid>"
}

curl -X POST "https://api.vidu.cn/live/s_editing/realtime" \
  -H "Authorization: vda_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/reference.png",
    "editing_type": "style_transfer",
    "rtc_info": {
      "provider": "trtc",
      "app_id": "<your_app_id>",
      "channel_id": "<your_channel_id>",
      "user_id": "<edited_result_uid>",
      "sub_user_id": "<your_app_pushing_uid>",
      "token": "<token_for_edited_result_uid>"
    }
  }'

Response example

{
  "live": {
    "id": "995200676634042368",
    "status": "waiting"
  },
  "rtc": null,
  "render_uid": "",
  "client_secret": "xxx"
}

Response parameters

live object fields

status enum values

Establish the WebSocket connection

Once created, establish the WebSocket control connection:

# Browser: client_secret as a query parameter
wss://api.vidu.cn/live/ws/live/connect?live_id=<live_id>&conn_id=<conn_id>&client_secret=<client_secret>

# Server-side Integration: Authorization Request Header
wss://api.vidu.cn/live/ws/live/connect?live_id=<live_id>&conn_id=<conn_id>
Authorization: vda_<your_api_key>

After the connection is established, send and receive messages as described in "WebSocket signals". If the connection drops unexpectedly, you can reconnect within the grace period reusing the same live_id and conn_id; if you do not reconnect in time, the live stream ends and billing stops.

Connection initialization signaling (type=1 / type=2)

A conn_init message must be sent immediately after the connection is established to initialize the connection, and the server will return a conn_init_ack. Upon receipt of this successful acknowledgment, the live stream enters the on_live state, and billing begins.

Request Example

{
  "type": 1,
  "live_id": "995200676634042368",
  "conn_id": "conn-xxx",
  "seq_id": 1,
  "payload": { "conn_init": { "version": 1 } }
}

{
  "type": 2,
  "live_id": "995200676634042368",
  "conn_id": "conn-xxx",
  "seq_id": 2,
  "payload": {
    "conn_init_ack": {
      "success": true,
      "error_code": "",
      "error_msg": "",
      "server_timestamp": "1789025863"
    }
  }
}

In case of failure, success is false, and error_code will be one of the "WebSocket Business Errors"—specifically NOT_READY, SIP_READY_TIMEOUT, LIVE_ENDED, or LIVE_CONN_INIT_FAILED—which should be handled according to the corresponding instructions. The seq_id in the response is the request's seq_id plus 1.

Image / scenario switch signal (type=13)

Request example

{
  "type": 13,
  "live_id": "995200676634042368",
  "conn_id": "conn-xxx",
  "seq_id": 2,
  "payload": {
    "switch_prompt": {
      "prompts": [{ "type": "image", "content": "https://example.com/new-reference.png" }],
      "editing_type": "virtual_tryon"
    }
  }
}

To change the reference image or editing scenario during a live stream, you must supply at least one of prompts or editing_type; both may be supplied together. If neither is supplied, the signal has no effect. On success, no acknowledgement is returned, and the composited picture switches to the new reference image / scenario within a few seconds. On failure, the server returns a type=14 acknowledgement (success=false, carrying error_code / error_msg); you can correct the request and resend it with a new seq_id. The server does not deduplicate signals, so sending the same one repeatedly triggers repeated switches.

Hangup (type=5)

Send the hangup signal when you are finished. The server stops the live stream, stops billing, and closes the connection.

Request example

{
  "type": 5,
  "live_id": "995200676634042368",
  "conn_id": "conn-xxx",
  "seq_id": 3,
  "payload": { "hangup": { "hangup_reason": "user_hangup" } }
}

Publishing and subscribing

Platform-managed channel (default, when rtc_info is not provided) Use the Alibaba Cloud RTC (AliRTC) SDK with the rtc credentials returned by the create call (app_id / channel_id / user_id / token) to join the channel. You must integrate the AliRTC SDK separately; for the web, refer to the Alibaba Cloud RTC Web SDK documentation and load the corresponding SDK in your page.

• Publish the editing input stream: after joining, publish the camera feed (or a local video file stream) as the editing input.
• Subscribe to the composited result: subscribe to the render_uid user's video stream in the channel — that is the real-time edited picture.
• Credential validity: join the channel before token_expire_at. A live stream that exceeds the maximum duration for a single session ends automatically. Using your own RTC channel (passing rtc_info) The platform no longer creates a channel; it connects directly to the real-time audio/video input using the channel and authentication information you provide in rtc_info, and produces the edited result stream inside your channel. In this case, rtc and render_uid in the create response are empty.
• Join the channel: use your own integrated RTC SDK (matching provider) to join the channel_id channel.
• Publish the editing input stream: publish the camera feed (or a local video file stream) under the identity sub_user_id; the platform subscribes to your input based on this ID. sub_user_id must match the user ID your App actually uses to publish.
• Subscribe to the edited result: the edited result stream is published in your channel under the identity user_id; subscribing to that user's video stream gets you the composited edited picture. Keep user_id distinct from the ID you use to publish.
• Authentication credential: token must match user_id. The platform does not validate its content — make sure the format and validity period are correct yourself.

RTMP relay

Passing rtmp_urls at creation time enables relaying. When the live stream starts, the server relays the composited result (that is, the render_uid rendered stream) as-is, as a single stream, to each address you supplied. You can watch it on the corresponding live platform using the playback address (for example, FLV or HLS).

• The relay address must be a push address on your own live platform (rtmp://). The push and playback addresses are provided by your live platform.
• The same push address cannot be used by multiple live streams at the same time; after a live stream ends, the same address cannot be reused immediately (roughly 10 seconds).
• Relaying forwards the original stream, so quality and resolution match the render_uid rendered stream in the channel.
• If the relay fails to start, the live stream ends immediately (see live.close_reason for the reason). Verify the address and create a new live stream.
• RTMP relay is not supported when using your own RTC channel (passing rtc_info); passing a non-empty rtmp_urls in that case returns 400.

Error responses

HTTP errors

When the create endpoint fails, it returns an HTTP status code with the following response body structure:

{
  "code": 400,
  "reason": "BAD_REQUEST",
  "message": "Invalid parameter",
  "metadata": {}
}

On failure, metadata may carry a trace_id. Provide it when contacting platform support.

WebSocket business errors

Connection initialization failures are returned with the type=2 acknowledgement, and image-switch failures with the type=14 acknowledgement (success=false). The reason is carried in the error_code field:

Billing

Live streams are billed by actual live duration in seconds, with the remainder settled when the stream ends. 1 credit per second (CNY 0.03125). Billing window: from the moment the server returns conn_init_ack.success=true (the stream enters on_live) until the hangup signal ends the live stream. Establishing the WebSocket connection alone or joining the RTC channel alone is not billed. After the live stream ends, you can call GET /live/v1/lives/{live_id} (using live.id) to read billed_seconds (billed seconds) and credits_cost (credits consumed).

FAQ