cancel_scheduled_briefing
ChatGPTCancel a scheduled briefing so it never fires again. Use it when the user asks to stop, cancel, remove or delete one. Only pass a task_id from list_scheduled_briefings, and only when it is clear which briefing they mean; if several could match, ask the user first.
create_audio_course
ChatGPTStart generating a SUN audio course from a topic prompt, optionally grounded in files the user attached (pass them in files) or uploaded with create_source_file_upload (pass their ids in file_ids). Returns a job_id immediately; poll get_course_status for progress. To narrate in a specific voice, pass a voice_id taken from list_voices; the course is then in that voice's language. To have SUN characters teach instead, pass one or two character_ids taken from list_characters: one narrates alone, two share every lecture and the first one leads. A voice and characters cannot be combined, and some two-character pairs are unavailable for courses built from files (SUN says so when it refuses). Pass course_language only when the user explicitly asks for a language; with a voice it must match the voice, and a character's own language never sets it.
create_meditation
ChatGPTStart generating a guided meditation the user listens to as one continuous session: breathing, a body scan, help relaxing, falling asleep or focusing. Not for learning about meditation (its science, history or benefits): that is a course, use create_audio_course. Pass purpose only when the user said what it is for or named a practice; if they did not, ask once, and omit it when they want to just start. Put the user's own words in request, including any breathing pattern or reason they gave. Returns a job_id immediately; poll get_course_status. Meditations use SUN's calm meditation voices: a voice_id from list_voices is kept only for some of the user's own cloned voices, and the result says when a chosen voice was replaced. Pass course_language only when the user explicitly asks for a language; with a voice it must match the voice.
create_song
ChatGPTStart composing an original song sung by SUN's music engine: a song, jingle, rap, lullaby, anthem, birthday song, lofi beats or relaxing music to listen to. A song for a child is still a song. Not for learning about music (its history or theory, how to write a song): that is a course, use create_audio_course. Put the user's request in song_request in their own words and language, keeping every name, detail, mood and genre. The engine refuses to imitate a real artist, band, song, album or composer and refuses existing lyrics or covers: replace only the imitation with a description of that sound (genre, era, instruments, tempo, mood, vocal delivery) and tell the user you did. An artist who is the song's subject stays as written. Pass length_seconds only when the user named a length; songs default to 180 seconds, never ask. A song has no narrator voice, characters or course language: its lyrics follow the request's language. Returns a job_id immediately; poll get_course_status.
create_source_file_upload
ChatGPTGet a one-time link to upload a file that exists only as a path on the user's computer, for clients that can read local files and run shell commands (such as Codex). Never needed in ChatGPT, where attachments go in create_audio_course's files. Call it once per file, then POST the file as multipart field 'file' to upload_url with header 'Authorization: Bearer <upload_token>' (the SUN plugin's upload_source_file.sh script does this, reading the token from SUN_UPLOAD_TOKEN). The response holds the file_id to pass in create_audio_course's file_ids. The link works once and expires after 10 minutes.
create_story
ChatGPTStart generating a piece of fiction told in chapters by one narrator: a bedtime story, a fairy tale, a fable, an adventure, or a made-up story about people the user names (their child, a friend). A story for a child is still a story. Not for non-fiction told as a story ('the story of Rome'), biographies, or analysing a novel: that is a course, use create_audio_course. Put the user's own words in request, keeping every name and detail. Returns a job_id immediately; poll get_course_status. A story is read by one narration voice, never by characters. To tell it in a voice, pass a voice_id from list_voices; when the user asks for their own voice, use one of their cloned voices (kind 'cloned'), and if they have none, say they can clone their voice in the SUN app (https://sunapp.ai) and offer one of SUN's voices instead. Pass course_language only when the user explicitly asks for a language; with a voice it must match the voice.
get_course
ChatGPTFetch current SUN course media, including its spoken intro and any lectures with audio ready. Set include_partial=true while generation continues or after an error to retrieve media already produced.
get_course_status
ChatGPTCheck the progress of a SUN course generation job.
get_credit_balance
ChatGPTHow many minutes of SUN credits the user has available. Use when the user asks about their balance. Uses no credits.
get_source_file_status
ChatGPTCheck how SUN is processing a file the user attached to a course (receiving, stored, parsing, parsed, or error with the reason).
list_characters
ChatGPTList the SUN characters that can teach a course, with each one's teaching style. A character's primary_language is part of their persona and does not set the course language. To have characters teach a course, their ids must come from this list: one narrates alone, two share every lecture and the first one leads.
list_scheduled_briefings
ChatGPTList the user's scheduled briefings with their ids, cadence and next time, including ones set up in the SUN app (origin says where each was created). Call it when the user asks what is scheduled, and before cancelling one so you act on the briefing they mean rather than a guess. Briefings cannot be edited: to change the time or topic, cancel it and schedule a new one, and only after the user agrees.
list_voices
ChatGPTList the voices a SUN course can be narrated in: SUN's own voices and the user's own cloned voices. Filter by course language with language. To narrate a course in a specific voice, its voice_id must come from this list.
schedule_briefing
ChatGPTSet up a recurring or one-off audio briefing on a topic instead of creating a course now. Nothing is generated when it is created: at each scheduled time SUN researches the topic and sends a push notification to the SUN app, and the briefing plays when the user taps it. Ask which city the user is in and pass its region time zone (e.g. 'Asia/Shanghai'); never guess it. Tell the user the briefing is set up only when this tool succeeds. If it fails, call list_scheduled_briefings before retrying so you do not create it twice. voice_id comes from list_voices and character_ids from list_characters; use one or the other.
wait_for_course
ChatGPTWait until a SUN generation job (course, meditation, story or song) has audio that can play. Call it right after any create tool, and again each time it returns state=waiting. Each call waits up to about 25 seconds on SUN's side, then returns state=playable (with listen_url and the media ready so far), waiting, failed or timed_out.
whoami
ChatGPTReturn the connected SUN account's profile: a stable opaque account ID and, when available, its email. Use when the user asks which SUN account is connected. Uses no credits.
