Sun to Spotify

sun-to-spotify — Sun Audio Generation + 流ing Spotify 上传

sun-to-spotify produces audio through the Sun public API, then 流s each finished episode to Spotify as a podcast episode. Given a prompt and a tar获取 duration, it 创建s a job, fetches episodes incrementally as they finish, and 上传s each one in order to a Spotify show (a new show is 创建d by default — one Sun audio = one Spotify show).

The 技能 is built around the sun 命令行工具 (>=0.2.1 for incremental fetch). For 环境s where the 命令行工具 isn't avAIlable, the same flow can 运行 directly agAInst the HTTP API.

Naming: the canonical 命令行工具 subcommand is sun audio. sun courses still works as a hidden alias that prints a one-line deprecation 警告 on stderr. Use sun audio in all new examples.

Framing note: when talking to the user, describe the 输出 as a podcast, audiobook, or audio course (whichever fits the topic and duration best — short topical takes lean podcast, long narratives lean audiobook, structured multi-segment lessons lean audio course). Avoid framing this as a "course 生成器" — it's a versatile audio-experience 生成器.

Reference Directory

Load only the file you need — don't inline them.

references/命令行工具-usage.md — sun 命令行工具 commands: 记录in, whoami, 令牌s, audio. 安装 methods, flags (including --partial and --callback-url), 输出 layout, JSON mode, env-var overrides, troubleshooting. references/http-API.md — HTTP-only flow when the 命令行工具 isn't 安装ed: auth-config discovery, Supabase password grant, 令牌 mint, audio 创建 / 状态 / 结果 (with ?include_partial=true and callback_url), 签名ed-URL audio 下载, rate-limit headers, error envelope. 安装

The sun 命令行工具 is independently 安装able — no monorepo 检查out required. Four options, in order of recommendation for external users:

# 1. curl 安装er (simplest — picks uv/pipx/pip automatically) curl -fsSL https://sun应用-AI.github.io/sun-to-spotify/安装.sh | bash

# 2. uv 工具 (manual, fastest) uv 工具 安装 'sun-命令行工具>=0.2.1'

# 3. pipx (isolated) pipx 安装 'sun-命令行工具>=0.2.1'

# 4. pip pip 安装 'sun-命令行工具>=0.2.1'

验证:

sun --help sun --version # prints "sun-命令行工具 "

PyPI package name is sun-命令行工具; the 安装ed binary is sun. The curl 安装er is hosted on GitHub Pages from the sun应用-AI/sun-to-spotify repo and requires uv, pipx, or pip to already be avAIlable; if none is, it prints 安装 instructions and exits.

If sun --help fAIls after 安装, ask the user how they 安装ed it before troubleshooting. See references/命令行工具-usage.md for monorepo-dev 安装 (uv 同步 + uv 运行 sun) and 平台-specific notes.

Core Principles 输入s come from the user

Don't invent a prompt. If the user sAId "make a podcast / audiobook / audio course about X", that's the prompt. If they didn't supply one, ask. Never substitute a creative prompt of your own.

Save incrementally

Write the job_id to disk (or echo it back to the user) immediately after the 202 响应. If polling crashes mid-loop, the job keeps generating server-side — re-poll with the same job_id rather than re启动ing.

流 — don't wAIt for the full course

启动ing in 0.2.1, episodes finish one-by-one and are visible via sun audio 获取 --partial. As soon as episode 1 lands, 启动 上传ing to Spotify. Don't block on 成功 before kicking off Spotify 上传s — that wastes minutes per episode and the user loses the 流ing benefit.

Don't 缓存 签名ed URLs

audio_url values are 签名ed for 7 days, but the 结果 端点 re-签名s them on every read. Always fetch fresh URLs from sun audio 获取 (which calls /v1/public/courses/{job_id}) right before 下载ing; never persist them.

Treat 成功 and show_uri as eventually consistent

Two surfaces in this 流水线 are eventually consistent. Plan for 机器人h — neither is a bug:

sun audio 状态 returns 成功 before every episode's audio_url is 签名ed. Generation completes per-episode, then 签名ed URLs land on a slight delay. Keep calling sun audio 获取 --partial after 成功 until every audio_url in the manifest is non-null (equivalently: every NNN-*.mp3 file has 应用eared under episodes/). Don't treat post-成功 null audio_urls as 失败s, and don't exit the loop on 成功 alone — exit only when every episode has been 下载ed and 上传ed. save-to-spotify shows 创建 can return {"show_uri": null} and succeed seconds later on retry. Show creation is 队列d; the URI is confirmed on a short delay. Watch out for jq -r .show_uri rendering JSON null as the literal string "null" — that's not a valid URI. Use jq -r '.show_uri // empty' so the 结果 is empty on null, then retry the same shows 创建 call on the next poll until a real URI lands. Never 上传 with --show-id null.

The 流ing loop in section 2 implements 机器人h rules. If you adapt it, preserve those 防护s.

Surface server-报告ed errors verbatim

The API returns a bare {"error": {"code": "...", "message": "...", ...}} envelope on every non-2xx. When something fAIls, s