videoclaw 3.0.0-alpha.1

package/src/video/providers/dreamina-useapi.ts

@@ -0,0 +1,345 @@
+import { withRetry, fetchTransientRetry } from '../with-retry.js';
+import { safeErrorBody } from '../http-error-safety.js';
+
+export type DreaminaModel =
+  | 'seedance-2.0'
+  | 'seedance-2.0-fast'
+  | 'seedance-1.5-pro'
+  | 'seedance-1.0-pro'
+  | 'seedance-1.0-mini'
+  | 'seedance-1.0-fast'
+  | 'sora2';
+export type DreaminaRegion = 'US' | 'CA';
+export type DreaminaAspectRatio = '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9';
+export type DreaminaResolution = '720p' | '1080p';
+/**
+ * Valid duration depends on the model:
+ *   - seedance-2.0 / seedance-2.0-fast: 4-15
+ *   - seedance-1.5-pro: 5, 10, 12
+ *   - seedance-1.0-*: 5, 10
+ *   - sora2: 4, 8, 12
+ * UseAPI enforces server-side; we ship the common Seedance-2 set.
+ */
+export type DreaminaDurationSeconds = 4 | 5 | 8 | 10 | 12 | 15;
+
+/**
+ * Minimal `fetch` shape that allows tests to inject a mock without depending
+ * on a full DOM `Response` type. Compatible with both `globalThis.fetch` and
+ * the matching helper in `../native-dreamina.ts`.
+ */
+export type DreaminaFetchLike = (
+  input: string,
+  init?: { method?: string; headers?: Record<string, string>; body?: string | Uint8Array },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  text: () => Promise<string>;
+  json: () => Promise<unknown>;
+}>;
+
+const USEAPI_BASE = 'https://api.useapi.net/v1';
+
+/**
+ * Dreamina Omni Reference budget (Seedance 2.0 via UseAPI's Dreamina proxy):
+ * up to 9 image refs + 3 video refs + 3 audio refs per submission — the same
+ * 9/3/3 reference budget Seedance enforces on every gateway. Emitted as the
+ * individual `omni_N_imageRef` / `omni_N_videoRef` / `omni_N_audioRef` fields.
+ */
+export const DREAMINA_MAX_IMAGE_REFS = 9;
+export const DREAMINA_MAX_VIDEO_REFS = 3;
+export const DREAMINA_MAX_AUDIO_REFS = 3;
+
+export interface SubmitDreaminaJobInput {
+  apiToken: string;
+  model: DreaminaModel;
+  prompt: string;
+  /**
+   * Dreamina account identifier, e.g. "CA:ai@3rdeye.co.uk". Optional on the API
+   * (auto-selected if omitted), but videoclaw always pins it so generations land
+   * on the configured CA 1080p account.
+   */
+  account?: string;
+  /** Video aspect ratio. Cannot be combined with firstFrameRef (image dictates ratio). */
+  ratio?: DreaminaAspectRatio;
+  duration?: DreaminaDurationSeconds;
+  resolution?: DreaminaResolution;
+  /**
+   * assetRef from POST /assets/<account> for the starting frame. Triggers
+   * `first_frame` (image-to-video) mode. When set, `ratio` is omitted because
+   * Dreamina auto-detects the ratio from the uploaded image.
+   */
+  firstFrameRef?: string;
+  /**
+   * Omni Reference (multi-character identity-lock): up to 9 image assetRefs,
+   * emitted as INDIVIDUAL `omni_1_imageRef`..`omni_9_imageRef` fields (NOT an
+   * array), per the UseAPI Dreamina contract. Mutually exclusive with the
+   * single-keyframe `firstFrameRef` frame-mode path: when any omni ref is
+   * present the builder emits the omni fields and drops `firstFrameRef`/`ratio`
+   * (Omni mode auto-detects the ratio from the references, like first_frame).
+   */
+  imageRefs?: string[];
+  /** Omni Reference videos: up to 3, emitted as omni_1_videoRef..omni_3_videoRef. */
+  videoRefs?: string[];
+  /** Omni Reference audios: up to 3, emitted as omni_1_audioRef..omni_3_audioRef. */
+  audioRefs?: string[];
+  /**
+   * Force a `ratio` in Omni Reference mode. Omni mode normally auto-detects the
+   * ratio from the references — but that defaults to landscape even for portrait
+   * refs, so a portrait project comes out 16:9. The Dreamina API DOES accept an
+   * explicit `ratio` alongside the omni_N fields (live-confirmed), so set this to
+   * pin the output orientation. Absent → ratio is dropped in Omni mode (legacy,
+   * byte-identical). Ignored outside Omni mode.
+   */
+  omniRatio?: DreaminaAspectRatio;
+  /**
+   * Opt-in: emit `audio: true` on the body. The Dreamina `/dreamina/videos`
+   * contract does NOT document an audio-generation parameter — the Omni Reference
+   * `omni_N_videoRef` (a black-frame voice video) is *expected* to drive the voice
+   * on its own. But the directly parallel Seedance-2 route (runway-useapi) needs an
+   * explicit `audio:true` for the voice to render, so this is an UNVERIFIED escape
+   * hatch: if a live Dreamina render with a bound voice comes back mute, set
+   * `VCLAW_DREAMINA_AUDIO=1` to send the flag. Default off → documented contract,
+   * byte-identical. Only emitted on the seedance-2.0 / seedance-2.0-fast models.
+   */
+  audio?: boolean;
+  /** Optional fetch override (defaults to global fetch). Used by tests + native wrapper. */
+  fetchImpl?: DreaminaFetchLike;
+}
+
+export interface SubmitDreaminaJobResult {
+  /** Namespaced jobid, e.g. "j0223...v-u12345-CA:user@example.com-bot:dreamina". Use as-is in poll. */
+  jobid: string;
+}
+
+/** POST https://api.useapi.net/v1/dreamina/videos — create video endpoint. */
+export function dreaminaVideosEndpoint(): string {
+  return `${USEAPI_BASE}/dreamina/videos`;
+}
+
+/** GET https://api.useapi.net/v1/dreamina/videos/{jobid} — poll endpoint. */
+export function dreaminaVideoJobEndpoint(jobid: string): string {
+  // UseAPI path params are passed verbatim (no encoding). The namespaced jobid
+  // contains ':' and '@' which are valid in URL paths.
+  return `${USEAPI_BASE}/dreamina/videos/${jobid}`;
+}
+
+/** POST https://api.useapi.net/v1/dreamina/assets/{account} — upload an image/asset. */
+export function dreaminaAssetsEndpoint(account: string): string {
+  return `${USEAPI_BASE}/dreamina/assets/${encodeURIComponent(account)}`;
+}
+
+export function buildDreaminaSubmitBody(input: SubmitDreaminaJobInput): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    prompt: input.prompt,
+    model: input.model,
+  };
+  if (input.account) body.account = input.account;
+  if (input.duration) body.duration = input.duration;
+  if (input.resolution) body.resolution = input.resolution;
+  // Unverified audio escape hatch (see SubmitDreaminaJobInput.audio). Seedance-2 only.
+  if (input.audio && (input.model === 'seedance-2.0' || input.model === 'seedance-2.0-fast')) {
+    body.audio = true;
+  }
+
+  // Omni Reference (multi-character) path: individual omni_N_imageRef /
+  // omni_N_videoRef / omni_N_audioRef fields (1-based, NOT an array), capped at
+  // 9/3/3. Mutually exclusive with the single-keyframe firstFrameRef frame mode:
+  // when any image/video/audio omni ref is present we drop firstFrameRef and
+  // ratio (Dreamina auto-detects the ratio in Omni mode just like first_frame).
+  const imageRefs = (input.imageRefs ?? []).filter(Boolean).slice(0, DREAMINA_MAX_IMAGE_REFS);
+  const videoRefs = (input.videoRefs ?? []).filter(Boolean).slice(0, DREAMINA_MAX_VIDEO_REFS);
+  const audioRefs = (input.audioRefs ?? []).filter(Boolean).slice(0, DREAMINA_MAX_AUDIO_REFS);
+
+  if (imageRefs.length > 0 || videoRefs.length > 0 || audioRefs.length > 0) {
+    imageRefs.forEach((ref, i) => {
+      body[`omni_${i + 1}_imageRef`] = ref;
+    });
+    videoRefs.forEach((ref, i) => {
+      body[`omni_${i + 1}_videoRef`] = ref;
+    });
+    audioRefs.forEach((ref, i) => {
+      body[`omni_${i + 1}_audioRef`] = ref;
+    });
+    // Omni mode auto-detects ratio by default; `omniRatio` forces it (the API
+    // accepts an explicit ratio here). Off → unchanged (no ratio in Omni mode).
+    if (input.omniRatio) body.ratio = input.omniRatio;
+  } else if (input.firstFrameRef) {
+    // first_frame mode: ratio is auto-detected from the image and cannot be sent.
+    body.firstFrameRef = input.firstFrameRef;
+  } else if (input.ratio) {
+    body.ratio = input.ratio;
+  }
+  return body;
+}
+
+export async function submitDreaminaJob(input: SubmitDreaminaJobInput): Promise<SubmitDreaminaJobResult> {
+  const body = buildDreaminaSubmitBody(input);
+  const fetchImpl = input.fetchImpl ?? (fetch as unknown as DreaminaFetchLike);
+  // Submit is a paid, non-idempotent generation POST (seedance-2.0 1080p costs
+  // ~57 credits/second). It is deliberately NOT wrapped in withRetry: replaying
+  // the same POST on a transient 5xx could create duplicate charged jobs if the
+  // provider accepted the first request before returning a gateway error.
+  // A single attempt; a transient failure surfaces to the caller. Poll (GET) is
+  // idempotent and keeps its retry below.
+  const response = await fetchImpl(dreaminaVideosEndpoint(), {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${input.apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Dreamina submit failed: ${response.status} ${safeErrorBody(text)}`);
+  }
+  const json = (await response.json()) as { jobid?: string; error?: string };
+  if (!json.jobid) {
+    throw new Error(`Dreamina submit returned unexpected shape (no jobid): ${JSON.stringify(json)}`);
+  }
+  return { jobid: json.jobid };
+}
+
+export type DreaminaPollStatus = 'pending' | 'completed' | 'failed';
+
+export interface DreaminaJobResponse {
+  /** Direct MP4 URL — clean master when available, watermarked fallback otherwise. */
+  videoUrl?: string;
+  videoUrlBackup?: string;
+  videoUrlWatermarked?: string;
+  watermarked?: boolean;
+  videoId?: string;
+  coverUrl?: string;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  hasAudio?: boolean;
+  assetId?: string;
+  [key: string]: unknown;
+}
+
+export interface PollDreaminaJobResult {
+  status: DreaminaPollStatus;
+  /** Direct MP4 URL of the completed video, when present. */
+  videoUrl: string | null;
+  /** Cover/thumbnail URL, when present. */
+  coverUrl: string | null;
+  /** Error summary on failure (e.g. "fail_code: 2043"). */
+  error: string | null;
+  raw: Record<string, unknown>;
+}
+
+/**
+ * Maps Dreamina's `status` string to videoclaw's tri-state. Dreamina reports
+ * `created` while a job is still generating; only `completed`/`failed` are
+ * terminal.
+ */
+export function mapDreaminaStatus(raw: string): DreaminaPollStatus {
+  const s = raw.toLowerCase();
+  if (s === 'completed') return 'completed';
+  if (s === 'failed') return 'failed';
+  return 'pending'; // created, queued, started, etc.
+}
+
+/** Parses a GET /videos/{jobid} response body into videoclaw's poll result. */
+export function parseDreaminaPollResponse(json: unknown): PollDreaminaJobResult {
+  const record = (json ?? {}) as {
+    status?: string;
+    error?: string;
+    errorDetails?: string;
+    response?: DreaminaJobResponse;
+  };
+  const status = mapDreaminaStatus(record.status ?? '');
+  const response = record.response ?? {};
+  const error = record.error
+    ? record.errorDetails
+      ? `${record.error} (${record.errorDetails})`
+      : record.error
+    : null;
+  return {
+    status,
+    videoUrl: typeof response.videoUrl === 'string' ? response.videoUrl : null,
+    coverUrl: typeof response.coverUrl === 'string' ? response.coverUrl : null,
+    error,
+    raw: (json ?? {}) as Record<string, unknown>,
+  };
+}
+
+export interface PollDreaminaJobInput {
+  apiToken: string;
+  /** Namespaced jobid from SubmitDreaminaJobResult. */
+  jobid: string;
+  /** Optional fetch override (defaults to global fetch). */
+  fetchImpl?: DreaminaFetchLike;
+}
+
+export async function pollDreaminaJob(input: PollDreaminaJobInput): Promise<PollDreaminaJobResult> {
+  const fetchImpl = input.fetchImpl ?? (fetch as unknown as DreaminaFetchLike);
+  // Retry transient network failures + HTTP 5xx; 4xx/non-ok flow through to the
+  // existing "Dreamina poll failed" message unchanged.
+  const response = await withRetry(() => fetchTransientRetry(fetchImpl, dreaminaVideoJobEndpoint(input.jobid), {
+    method: 'GET',
+    headers: { 'Authorization': `Bearer ${input.apiToken}` },
+  }));
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Dreamina poll failed: ${response.status} ${safeErrorBody(text)}`);
+  }
+  return parseDreaminaPollResponse(await response.json());
+}
+
+export interface UploadDreaminaAssetInput {
+  apiToken: string;
+  /** Dreamina account identifier, e.g. "CA:ai@3rdeye.co.uk". */
+  account: string;
+  /** Raw image bytes. */
+  bytes: Uint8Array;
+  /** Image MIME type (image/jpeg, image/png, image/webp). Defaults to image/jpeg. */
+  contentType?: string;
+  /** Optional fetch override (defaults to global fetch). */
+  fetchImpl?: DreaminaFetchLike;
+}
+
+export interface UploadDreaminaAssetResult {
+  /** assetRef used as firstFrameRef / endFrameRef / frame_N_imageRef in POST /videos. */
+  assetRef: string;
+  width: number | null;
+  height: number | null;
+}
+
+/**
+ * Uploads raw image bytes to Dreamina and returns the `assetRef` to use as a
+ * keyframe (first frame) in a video generation request.
+ */
+export async function uploadDreaminaAsset(input: UploadDreaminaAssetInput): Promise<UploadDreaminaAssetResult> {
+  const fetchImpl = input.fetchImpl ?? (fetch as unknown as DreaminaFetchLike);
+  const response = await fetchImpl(dreaminaAssetsEndpoint(input.account), {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${input.apiToken}`,
+      'Content-Type': input.contentType ?? 'image/jpeg',
+    },
+    body: input.bytes,
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Dreamina asset upload failed: ${response.status} ${safeErrorBody(text)}`);
+  }
+  // assetRef is the canonical field; imageRef is a legacy alias (images only).
+  const json = (await response.json()) as {
+    assetRef?: string;
+    imageRef?: string;
+    width?: number;
+    height?: number;
+    error?: string;
+  };
+  const assetRef = json.assetRef ?? json.imageRef;
+  if (!assetRef) {
+    throw new Error(`Dreamina asset upload returned no assetRef: ${JSON.stringify(json)}`);
+  }
+  return {
+    assetRef,
+    width: typeof json.width === 'number' ? json.width : null,
+    height: typeof json.height === 'number' ? json.height : null,
+  };
+}

package/src/video/providers/flowmusic-useapi.ts

@@ -0,0 +1,252 @@
+/**
+ * FlowMusic (useapi.net) transport — Google Lyria 3 Pro vocal-song generation.
+ *
+ * Pure transport: submit → poll → download. Mirrors providers/dreamina-useapi.ts
+ * (async job, namespaced jobid, signed-URL/auth download) and reuses the SAME
+ * useapi.net bearer token as the dreamina/runway routes (USEAPI_API_TOKEN).
+ *
+ * AUTHORITATIVE SPEC: https://useapi.net/assets/aibot/api-flowmusic-v1.txt
+ * (the rendered docs page returns fabricated fields — do not trust it). Key
+ * facts encoded here: status enum is exactly pending|completed|failed (NO
+ * submitted/processing); `POST /flowmusic/music` with mode:'async' returns a
+ * jobid to poll; each generation yields up to TWO clips (an A/B pair) each with
+ * a signed `audio_url` (m4a) + `wav_url`, plus an encoded `clip` id usable with
+ * the auth'd `GET /flowmusic/music/download?id=<clip>&format=mp3` (raw mp3
+ * bytes). The jobid contains ':' and '@' and MUST be percent-encoded in the
+ * poll/download paths.
+ */
+
+import { withRetry, fetchTransientRetry } from '../with-retry.js';
+
+export type FlowMusicGhostwriter = 'standard' | 'pro';
+
+/**
+ * Minimal `fetch` shape that lets tests inject a mock. Adds `arrayBuffer()` for
+ * the binary mp3 download endpoint (submit/poll only need json()/text()).
+ */
+export type FlowMusicFetchLike = (
+  input: string,
+  init?: { method?: string; headers?: Record<string, string>; body?: string | Uint8Array },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  text: () => Promise<string>;
+  json: () => Promise<unknown>;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+}>;
+
+const USEAPI_BASE = 'https://api.useapi.net/v1';
+const FLOWMUSIC_BASE = `${USEAPI_BASE}/flowmusic`;
+
+/** Prompt length ceiling per the FlowMusic spec. */
+export const FLOWMUSIC_MAX_PROMPT_CHARS = 10000;
+
+export interface SubmitFlowMusicJobInput {
+  apiToken: string;
+  /** Song description (style, mood, genre, instruments, BPM, vocal direction). Required, 1..10000 chars. */
+  prompt: string;
+  /** flowmusic.app account email to pin; omitted → useapi auto-selects an account with capacity. */
+  account?: string;
+  /** Force an instrumental render (prepends an [Instrumental] tag). Only emitted when true. */
+  instrumental?: boolean;
+  /** User-supplied lyrics ([Verse]/[Chorus]-tagged). Present ⇒ a vocal render of these words. */
+  lyrics?: string;
+  /** Lyrics-writer version used when the MODEL writes lyrics; ignored by the API when lyrics are supplied. */
+  ghostwriter?: FlowMusicGhostwriter;
+  /** Optional fetch override (defaults to global fetch). Used by tests + the native backend. */
+  fetchImpl?: FlowMusicFetchLike;
+}
+
+export interface SubmitFlowMusicJobResult {
+  /** Namespaced jobid, e.g. "job:<uuid>-user:<id>-<email>-bot:flowmusic". Percent-encode in poll. */
+  jobid: string;
+  status: FlowMusicPollStatus;
+}
+
+/** POST https://api.useapi.net/v1/flowmusic/music — create song endpoint. */
+export function flowmusicMusicEndpoint(): string {
+  return `${FLOWMUSIC_BASE}/music`;
+}
+
+/** GET https://api.useapi.net/v1/flowmusic/jobs/{jobid} — poll endpoint (jobid percent-encoded). */
+export function flowmusicJobEndpoint(jobid: string): string {
+  // The namespaced jobid contains ':' and '@'; FlowMusic requires it encoded.
+  return `${FLOWMUSIC_BASE}/jobs/${encodeURIComponent(jobid)}`;
+}
+
+/** GET https://api.useapi.net/v1/flowmusic/music/download?id={clip}&format=mp3 — raw mp3 bytes (auth). */
+export function flowmusicDownloadEndpoint(clip: string): string {
+  return `${FLOWMUSIC_BASE}/music/download?id=${encodeURIComponent(clip)}&format=mp3`;
+}
+
+/**
+ * Builds the `POST /flowmusic/music` body. Always `mode:'async'` so submit
+ * returns a jobid to poll rather than blocking the CLI for the ~40–150 s sync
+ * render. Optional fields are omitted when unset (never sent null), matching the
+ * dreamina/suno convention.
+ */
+export function buildFlowMusicSubmitBody(input: SubmitFlowMusicJobInput): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    prompt: input.prompt,
+    mode: 'async',
+  };
+  if (input.account) body.email = input.account;
+  if (input.instrumental === true) body.instrumental = true;
+  if (input.lyrics && input.lyrics.trim() !== '') body.lyrics = input.lyrics;
+  if (input.ghostwriter) body.ghostwriter = input.ghostwriter;
+  return body;
+}
+
+export async function submitFlowMusicJob(
+  input: SubmitFlowMusicJobInput,
+): Promise<SubmitFlowMusicJobResult> {
+  const body = buildFlowMusicSubmitBody(input);
+  const fetchImpl = input.fetchImpl ?? (fetch as unknown as FlowMusicFetchLike);
+  // Paid, non-idempotent generation POST (~5 credits) — deliberately NOT
+  // retried: replaying on a transient 5xx could create a duplicate charged job
+  // if the provider accepted the first request before the gateway error. Poll
+  // (GET) is idempotent and keeps its retry below.
+  const response = await fetchImpl(flowmusicMusicEndpoint(), {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${input.apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`FlowMusic submit failed: ${response.status} ${text}`);
+  }
+  const json = (await response.json()) as { jobid?: string; status?: string };
+  if (!json.jobid) {
+    throw new Error(`FlowMusic submit returned unexpected shape (no jobid): ${JSON.stringify(json)}`);
+  }
+  return { jobid: json.jobid, status: mapFlowMusicStatus(json.status ?? 'pending') };
+}
+
+export type FlowMusicPollStatus = 'pending' | 'completed' | 'failed';
+
+export interface FlowMusicClip {
+  /** Encoded clip asset id; used with /music/download and /music/edit. */
+  clip: string;
+  title: string | null;
+  /** Clip length in seconds, when present on the job record. */
+  durationS: number | null;
+  /** Signed m4a URL (public, no auth) when present. */
+  audioUrl: string | null;
+  /** Signed wav URL (public, no auth) when present. */
+  wavUrl: string | null;
+  /** Auto-generated artwork URL, when present. */
+  imageUrl: string | null;
+}
+
+export interface PollFlowMusicJobResult {
+  status: FlowMusicPollStatus;
+  /** Up to two clips (an A/B pair) on a completed job. */
+  clips: FlowMusicClip[];
+  /** Error summary on failure, e.g. "moderation_reject: ...". */
+  error: string | null;
+  raw: Record<string, unknown>;
+}
+
+/** FlowMusic status is exactly pending|completed|failed (no submitted/processing/created). */
+export function mapFlowMusicStatus(raw: string): FlowMusicPollStatus {
+  const s = raw.toLowerCase();
+  if (s === 'completed') return 'completed';
+  if (s === 'failed') return 'failed';
+  return 'pending';
+}
+
+/** Defensive parse of a single clip object; returns null if it lacks a clip id. */
+function parseClip(raw: unknown): FlowMusicClip | null {
+  if (typeof raw !== 'object' || raw === null) return null;
+  const c = raw as Record<string, unknown>;
+  const clip = typeof c.clip === 'string' ? c.clip : null;
+  if (!clip) return null;
+  return {
+    clip,
+    title: typeof c.title === 'string' ? c.title : null,
+    durationS: typeof c.duration_s === 'number' ? c.duration_s : null,
+    audioUrl: typeof c.audio_url === 'string' ? c.audio_url : null,
+    wavUrl: typeof c.wav_url === 'string' ? c.wav_url : null,
+    imageUrl: typeof c.image_url === 'string' ? c.image_url : null,
+  };
+}
+
+/** Parses a GET /jobs/{jobid} (or sync POST) response into videoclaw's poll result. */
+export function parseFlowMusicJobResponse(json: unknown): PollFlowMusicJobResult {
+  const record = (json ?? {}) as {
+    status?: string;
+    clips?: unknown;
+    error?: { code?: string; message?: string } | string;
+  };
+  const status = mapFlowMusicStatus(record.status ?? '');
+  const clips = Array.isArray(record.clips)
+    ? record.clips.map(parseClip).filter((c): c is FlowMusicClip => c !== null)
+    : [];
+  let error: string | null = null;
+  if (record.error) {
+    if (typeof record.error === 'string') {
+      error = record.error;
+    } else {
+      const code = record.error.code ?? '';
+      const message = record.error.message ?? '';
+      error = [code, message].filter(Boolean).join(': ') || null;
+    }
+  }
+  return { status, clips, error, raw: (json ?? {}) as Record<string, unknown> };
+}
+
+export interface PollFlowMusicJobInput {
+  apiToken: string;
+  /** Namespaced jobid from SubmitFlowMusicJobResult. */
+  jobid: string;
+  fetchImpl?: FlowMusicFetchLike;
+}
+
+export async function pollFlowMusicJob(input: PollFlowMusicJobInput): Promise<PollFlowMusicJobResult> {
+  const fetchImpl = input.fetchImpl ?? (fetch as unknown as FlowMusicFetchLike);
+  // Retry transient network failures + HTTP 5xx; 4xx/non-ok flow through to the
+  // "FlowMusic poll failed" message unchanged.
+  const response = await withRetry(() =>
+    fetchTransientRetry(fetchImpl, flowmusicJobEndpoint(input.jobid), {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${input.apiToken}` },
+    }),
+  );
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`FlowMusic poll failed: ${response.status} ${text}`);
+  }
+  return parseFlowMusicJobResponse(await response.json());
+}
+
+export interface DownloadFlowMusicClipInput {
+  apiToken: string;
+  /** Encoded clip asset id from a completed job's clips[].clip. */
+  clip: string;
+  fetchImpl?: FlowMusicFetchLike;
+}
+
+/**
+ * Fetches raw mp3 bytes for a completed clip via the auth'd download endpoint.
+ * Keeps the MusicBackend `.mp3` contract intact (the signed audio_url is m4a).
+ */
+export async function downloadFlowMusicClipMp3(
+  input: DownloadFlowMusicClipInput,
+): Promise<Uint8Array> {
+  const fetchImpl = input.fetchImpl ?? (fetch as unknown as FlowMusicFetchLike);
+  const response = await withRetry(() =>
+    fetchTransientRetry(fetchImpl, flowmusicDownloadEndpoint(input.clip), {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${input.apiToken}` },
+    }),
+  );
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`FlowMusic download failed: ${response.status} ${text}`);
+  }
+  const buf = await response.arrayBuffer();
+  return new Uint8Array(buf);
+}