Announcements

Play an announcement now

POST
https://api.tunio.ai/v1/stream/{stream_id}/announcements/{announcement_id}/play

Puts a completed announcement of the caller's library on air on a stream right away, without scheduling it. By default (playback.mode cut) the song on air stops, the announcement plays (with the alert tone before and after it when the announcement has it) and the music goes on. Content already on air (news, a podcast, another announcement, a jingle) is not cut unless priority is high; the announcement then plays right after it. During a live broadcast nothing interrupts the host: the announcement waits, and with priority high plays as soon as the broadcast ends (otherwise it is dropped with the rest of the content queued during live). The request is accepted when the announcement is handed to the stream; whether and when it aired shows in GET /v1/stream/{stream_id}/history (kind announcement, track_id = announcement_id). Playing costs no credits. The stream must be running. Requires a plan with API access. Rate limited to 60 calls per minute per account.

路径参数

名称类型说明
stream_idRequiredstringStream ID
announcement_idRequiredstringAnnouncement ID

请求体

How to play it

名称类型说明
idempotency_keystring
Optional, up to 128 characters. A second request with the same key for the same stream within 10 minutes plays nothing and answers duplicate=true, so a retried webhook does not air the announcement twice.
playbackobject
How the announcement goes on air: mode cut (default) stops the song on air and plays it at once, after_track plays it after the current song, voiceover reads it over the song (needs the advanced stream sound plan; without it, it plays after the song). duck, fade_down and fade_up tune the voice-over.
ducknumber
Voice-over only: music level under the voice, 0..1 (0 mutes the music, 1 leaves it as is). Omit it for the default, 0.2.
fade_downnumber
Voice-over only: seconds the music takes to go down before the voice, 0..10. Omit it for the default, 0.8.
fade_upnumber
Voice-over only: seconds the music takes to come back after the voice, 0..10. Omit it for the default, 1.5.
modestring
Required whenever playback is sent. after_track waits for the song on air to end, cut interrupts the song, voiceover reads the announcement over the song (needs a plan with advanced stream sound, otherwise it plays after the song).
prioritystring
normal (default) or high. high always plays at once (mode cut): it also cuts news, podcasts, other announcements and jingles on air, goes ahead of content already queued and, when a live broadcast has the air, plays as soon as it ends instead of being dropped. It does not interrupt the live broadcast itself.
请求示例
01{
02 "idempotency_key": "alert-2026-11-20T11:55",
03 "playback": {
04 "duck": 0.2,
05 "fade_down": 0.8,
06 "fade_up": 1.5,
07 "mode": "voiceover"
08 },
09 "priority": "normal"
10}

响应

名称类型说明
duplicateboolean
true when the idempotency_key was already used for this stream in the last 10 minutes and nothing was played.
successboolean
Always true.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
名称类型说明
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.