@j-o-r/hello-dave 0.1.1 → 0.1.4

package/types/API/minimax/music.d.ts

@@ -1,38 +1,201 @@
-export function getHeaders(): {
-    'Content-Type': string;
-    Authorization: string;
-};
-export function saveAudioToLocal(audioData: any, filenamePrefix?: string): Promise<any>;
-export function createMusic(prompt: any, options?: {}): Promise<{
-    audio_url: any;
-    local_path: any;
+/**
+ * Get authentication headers for Minimax API.
+ *
+ * @returns {Object} Headers object with Authorization Bearer token.
+ * @throws {Error} If MINIMAX_API_KEY environment variable is not set.
+ */
+export function getHeaders(): Object;
+/**
+ * Saves audio data (URL or hex) to a local temporary MP3 file.
+ *
+ * @param {string} audioData - Either a URL or hex-encoded audio data.
+ * @param {string} [filenamePrefix='minimax-music'] - Prefix for the local filename.
+ * @returns {Promise<string>} Absolute path to the saved local file.
+ */
+export function saveAudioToLocal(audioData: string, filenamePrefix?: string): Promise<string>;
+/**
+ * Generate music from a text prompt (text-to-music workflow).
+ *
+ * Uses models `music-2.6` or `music-2.6-free`.
+ * Does NOT support reference audio (use changeMusic() or analyzeMusic() instead).
+ *
+ * @param {string} prompt - Description of the music (style, mood, scenario). Max 2000 chars.
+ * @param {Object} [options={}] - Generation options.
+ *
+ * @param {string} [options.model='music-2.6'] - Model to use.
+ *   - 'music-2.6' (default, recommended, higher RPM)
+ *   - 'music-2.6-free' (free tier, lower RPM)
+ *
+ * @param {string} [options.lyrics] - Song lyrics with structure tags (e.g. [Verse], [Chorus]).
+ *   Required for non-instrumental. Max 3500 chars.
+ *
+ * @param {boolean} [options.is_instrumental=false] - Generate instrumental music (no vocals).
+ *   When true, lyrics are optional.
+ *
+ * @param {boolean} [options.lyrics_optimizer=false] - Auto-generate lyrics from prompt when lyrics is empty.
+ *
+ * @param {string} [options.output_format='url'] - 'url' or 'hex'. URL links expire after 24h.
+ *
+ * @param {Object} [options.extra] - Any additional undocumented parameters.
+ *
+ * @returns {Promise<{
+ *   audio_url: string,      // Original URL or hex data
+ *   local_path: string,     // Path in .cache/minimax/
+ *   duration: number,       // API call time in ms
+ *   raw: object             // Full API response
+ * }>}
+ *
+ * @throws {Error} If reference audio params are provided or invalid model.
+ *
+ * @example
+ * const result = await createMusic("Indie folk, melancholic", {
+ *   model: "music-2.6",
+ *   lyrics: "[Verse]\n...",
+ *   is_instrumental: false
+ * });
+ */
+export function createMusic(prompt: string, options?: {
+    model?: string | undefined;
+    lyrics?: string | undefined;
+    is_instrumental?: boolean | undefined;
+    lyrics_optimizer?: boolean | undefined;
+    output_format?: string | undefined;
+    extra?: Object | undefined;
+}): Promise<{
+    audio_url: string;
+    local_path: string;
     duration: number;
-    raw: any;
+    raw: object;
 }>;
-export function changeMusic(prompt: any, options?: {}): Promise<{
-    audio_url: any;
-    local_path: any;
+/**
+ * Generate a cover version of reference music (music-cover workflow).
+ *
+ * **Model is fixed to 'music-cover'** (the recommended paid model).
+ * The free variant ('music-cover-free') is not supported for changeMusic().
+ *
+ * Requires either direct reference audio OR a preprocessed cover_feature_id.
+ *
+ * **Critical rule for two-step covers (cover_feature_id)**:
+ *   - When `cover_feature_id` is used **and** `is_instrumental` is false (non-instrumental),
+ *     the `lyrics` parameter is **mandatory**.
+ *   - When using direct `audio_url`/`audio_base64`, lyrics are optional (API can extract via ASR).
+ *
+ * **Prompt limit**: Max 300 characters (strictly enforced for music-cover models).
+ * **audio_setting**: Fixed internally to { sample_rate: 44100, bitrate: 256000, format: 'mp3' }.
+ *   User-provided audio_setting is ignored.
+ *
+ * @param {string} prompt - Description of the target cover style. Max 300 chars.
+ * @param {Object} [options={}] - Generation options (model is ignored — always 'music-cover').
+ *
+ * @param {string} [options.audio_url] - URL of reference audio (6s–6min, ≤50MB).
+ *   Mutually exclusive with cover_feature_id.
+ *
+ * @param {string} [options.audio_base64] - Base64 reference audio (alternative to audio_url).
+ *
+ * @param {string} [options.cover_feature_id] - Feature ID from analyzeMusic() for two-step covers.
+ *   **Requires lyrics** when is_instrumental=false. Valid for 24h. Mutually exclusive with audio refs.
+ *
+ * @param {string} [options.lyrics] - Lyrics for the cover (mandatory for cover_feature_id + non-instrumental).
+ *
+ * @param {boolean} [options.lyrics_optimizer=false] - Auto-generate lyrics from prompt.
+ *
+ * @param {string} [options.output_format='url'] - 'url' or 'hex'.
+ *
+ * @param {Object} [options.extra] - Additional parameters.
+ *
+ * @returns {Promise<{audio_url: string, local_path: string, duration: number, raw: object}>}
+ *
+ * @throws {Error} On missing reference, conflicting params, prompt > 300 chars, or missing lyrics for two-step non-instrumental.
+ *
+ * @example
+ * // One-step cover
+ * const result = await changeMusic("Pop cover style", {
+ *   audio_url: "https://example.com/reference.mp3"
+ * });
+ *
+ * @example
+ * // Two-step cover (after analyzeMusic) — lyrics REQUIRED
+ * const result = await changeMusic("New lyrics style", {
+ *   cover_feature_id: "abc123...",
+ *   lyrics: "[Verse]\nNew lyrics...",
+ *   is_instrumental: false
+ * });
+ */
+export function changeMusic(prompt: string, options?: {
+    audio_url?: string | undefined;
+    audio_base64?: string | undefined;
+    cover_feature_id?: string | undefined;
+    lyrics?: string | undefined;
+    lyrics_optimizer?: boolean | undefined;
+    output_format?: string | undefined;
+    extra?: Object | undefined;
+}): Promise<{
+    audio_url: string;
+    local_path: string;
     duration: number;
-    raw: any;
+    raw: object;
 }>;
-export function analyzeMusic(audioUrl: any, options?: {}): Promise<{
-    cover_feature_id: any;
-    formatted_lyrics: any;
-    structure_result: any;
-    audio_duration: any;
-    trace_id: any;
-    raw: any;
+/**
+ * Preprocess a reference audio to extract features and structured lyrics.
+ *
+ * Used for the two-step cover workflow (analyze → changeMusic with cover_feature_id).
+ * **Model is fixed to 'music-cover'**.
+ *
+ * @param {string} audioUrl - URL of the reference audio (6s–6min, ≤50MB).
+ * @param {Object} [options={}] - Optional parameters (model is ignored).
+ *
+ * @returns {Promise<{
+ *   cover_feature_id: string,   // Valid 24h, use in changeMusic()
+ *   formatted_lyrics: string,   // Structured lyrics with [Verse] etc.
+ *   structure_result: string,   // JSON song structure analysis
+ *   audio_duration: number,
+ *   trace_id: string,
+ *   raw: object
+ * }>}
+ *
+ * @example
+ * const analysis = await analyzeMusic("https://example.com/song.mp3");
+ * // Then pass analysis.cover_feature_id to changeMusic()
+ */
+export function analyzeMusic(audioUrl: string, options?: Object): Promise<{
+    cover_feature_id: string;
+    formatted_lyrics: string;
+    structure_result: string;
+    audio_duration: number;
+    trace_id: string;
+    raw: object;
 }>;
 /**
  * Generate complete song lyrics or edit/continue existing lyrics.
  *
- * @param {string} prompt - Theme, style, or editing instruction.
- * @param {Object} [options]
- * @param {'write_full_song'|'edit'} [options.mode='write_full_song']
- * @param {string} [options.lyrics] - Existing lyrics (required for edit mode)
- * @param {string} [options.title]
+ * @param {string} prompt - Theme, style, or editing instruction. Max 2000 chars.
+ * @param {Object} [options={}] - Lyrics options.
+ *
+ * @param {'write_full_song'|'edit'} [options.mode='write_full_song'] - Generation mode.
+ *   - 'write_full_song': Create a new complete song.
+ *   - 'edit': Edit or continue existing lyrics (requires options.lyrics).
+ *
+ * @param {string} [options.lyrics] - Existing lyrics (required for 'edit' mode). Max 3500 chars.
+ *
+ * @param {string} [options.title] - Desired song title (preserved if provided).
+ *
+ * @returns {Promise<{
+ *   song_title: string,
+ *   style_tags: string,     // Comma-separated tags
+ *   lyrics: string,         // Structured lyrics ready for music generation
+ *   raw: object
+ * }>}
+ *
+ * @example
+ * // Full song
+ * const lyrics = await generateLyrics("Cheerful love song about summer beach");
  *
- * @returns {Promise<{song_title: string, style_tags: string, lyrics: string, raw: object}>}
+ * @example
+ * // Edit mode
+ * const edited = await generateLyrics("Make it more upbeat", {
+ *   mode: "edit",
+ *   lyrics: existingLyrics
+ * });
  */
 export function generateLyrics(prompt: string, options?: {
     mode?: "write_full_song" | "edit" | undefined;

package/types/API/minimax/video.d.ts

@@ -20,23 +20,58 @@ export function saveVideoToLocal(videoUrl: string, filenamePrefix?: string): Pro
  * Uses POST /v1/video_generation.
  * Supports all documented models and input types via options.
  *
- * @param {string} [prompt] - Text description (required for most modes).
- * @param {Object} [options]
+ * The function now includes **clear validation** so you get an explicit error
+ * instead of a cryptic API rejection.
  *
- * @param {string} [options.model='MiniMax-Hailuo-2.3'] - Default model.
- *   Supported: MiniMax-Hailuo-2.3, MiniMax-Hailuo-02, T2V-01, I2V-01, S2V-01, etc.
+ * @param {string} [prompt=''] - Text description (required for most modes). Max 2000 chars.
+ *   Supports camera commands in [] for supported models, e.g. [Pan left], [Truck right].
+ * @param {Object} [options={}] - Generation options.
  *
- * @param {string} [options.first_frame_image] - URL or data: URL for image-to-video / first-last.
- * @param {string} [options.last_frame_image] - For first & last frame mode.
- * @param {Array<Object>} [options.subject_reference] - For subject-reference mode.
+ * @param {string} [options.model] - Model name. If omitted, a sensible default is chosen based on mode.
+ *   See the mapping table at the top of this file.
  *
- * @param {boolean} [options.prompt_optimizer=true]
- * @param {boolean} [options.fast_pretreatment=false]
- * @param {number} [options.duration=6]
- * @param {string} [options.resolution] - e.g. '768P', '1080P'
- * @param {string} [options.callback_url]
+ * @param {string} [options.first_frame_image] - **Public HTTP/HTTPS URL only** (no Base64/data: URLs).
  *
- * @returns {Promise<{task_id: string, raw: object}>}
+ * @param {string} [options.last_frame_image] - **Public HTTP/HTTPS URL only** (no Base64/data: URLs) — First & Last Frame mode only.
+ *
+ * @param {Array<Object>} [options.subject_reference] - For subject-reference mode (S2V-01 only).
+ *   Each item must be `{ type: "character", image: ["https://..."] }` with **exactly one URL** in the image array.
+ *
+ * @param {boolean} [options.prompt_optimizer=true] - Auto-optimize prompt (default true).
+ *
+ * @param {boolean} [options.fast_pretreatment=false] - Reduce optimization time (Hailuo models only).
+ *
+ * @param {number} [options.duration=6] - Video length in seconds (model/resolution dependent).
+ *
+ * @param {string} [options.resolution] - e.g. '768P', '1080P', '720P' (model dependent).
+ *
+ * @param {string} [options.callback_url] - Optional webhook for async status updates.
+ *
+ * @param {Object} [options.extra] - Any additional parameters.
+ *
+ * @returns {Promise<{task_id: string, duration: number, raw: object}>}
+ *
+ * @example
+ * // Text-to-Video (default)
+ * await createVideoGenerationTask("A cat jumping [Pan left]", { model: "MiniMax-Hailuo-2.3" });
+ *
+ * @example
+ * // First & Last Frame — MUST use MiniMax-Hailuo-02 + public URLs
+ * await createVideoGenerationTask("", {
+ *   model: "MiniMax-Hailuo-02",
+ *   first_frame_image: "https://example.com/first.jpg",
+ *   last_frame_image: "https://example.com/last.jpg"
+ * });
+ *
+ * @example
+ * // Subject-Reference (S2V-01) — exactly one image per reference
+ * await createVideoGenerationTask("...", {
+ *   model: "S2V-01",
+ *   subject_reference: [
+ *     { type: "character", image: ["https://example.com/puppet.jpg"] },
+ *     { type: "character", image: ["https://example.com/girl.png"] }
+ *   ]
+ * });
  */
 export function createVideoGenerationTask(prompt?: string, options?: {
     model?: string | undefined;
@@ -48,8 +83,10 @@ export function createVideoGenerationTask(prompt?: string, options?: {
     duration?: number | undefined;
     resolution?: string | undefined;
     callback_url?: string | undefined;
+    extra?: Object | undefined;
 }): Promise<{
     task_id: string;
+    duration: number;
     raw: object;
 }>;
 /**
@@ -57,7 +94,7 @@ export function createVideoGenerationTask(prompt?: string, options?: {
  *
  * GET /v1/query/video_generation?task_id=...
  *
- * @param {string} taskId
+ * @param {string} taskId - The task_id returned by createVideoGenerationTask.
  * @returns {Promise<{
  *   task_id: string,
  *   status: 'Preparing' | 'Queueing' | 'Processing' | 'Success' | 'Fail',
@@ -80,7 +117,7 @@ export function queryVideoGenerationTask(taskId: string): Promise<{
  *
  * GET /v1/files/retrieve?file_id=...
  *
- * @param {string|number} fileId
+ * @param {string|number} fileId - The file_id from a successful query.
  * @returns {Promise<{
  *   file_id: string,
  *   filename: string,
@@ -101,13 +138,13 @@ export function retrieveVideoFile(fileId: string | number): Promise<{
  * Handles the full async flow: create task → poll until ready → retrieve → download to .cache/minimax/
  *
  * Supports all video generation modes (text, image-to-video, first-last, subject-ref)
- * by passing the appropriate options.
+ * by passing the appropriate options. **Model validation + strict public-URL validation** are enforced.
  *
  * @param {string} prompt - Text prompt (can be empty for some modes).
- * @param {Object} [options] - Same as createVideoGenerationTask + polling options.
+ * @param {Object} [options={}] - Same as createVideoGenerationTask + polling options.
  *
- * @param {number} [options.max_wait_ms=300000]
- * @param {number} [options.poll_interval_ms=5000]
+ * @param {number} [options.max_wait_ms=300000] - Max polling time (5 minutes).
+ * @param {number} [options.poll_interval_ms=5000] - Polling interval in ms.
  *
  * @returns {Promise<{
  *   task_id: string,
@@ -121,18 +158,11 @@ export function retrieveVideoFile(fileId: string | number): Promise<{
  * }>}
  *
  * @example
- * // Text-to-Video
- * const result = await generateVideo("A cat jumping on a table [Pan left]", {
- *   model: "MiniMax-Hailuo-2.3",
- *   duration: 6,
- *   resolution: "768P"
- * });
- *
- * @example
- * // Image-to-Video
- * const result = await generateVideo("The character walks forward", {
- *   model: "MiniMax-Hailuo-2.3",
- *   first_frame_image: "https://example.com/image.jpg"
+ * // First & Last Frame (correct model + public URLs only)
+ * const result = await generateVideo("", {
+ *   model: "MiniMax-Hailuo-02",
+ *   first_frame_image: "https://example.com/first.jpg",
+ *   last_frame_image: "https://example.com/last.jpg"
  * });
  */
 export function generateVideo(prompt?: string, options?: {
@@ -163,3 +193,42 @@ export function waitForVideoReady(taskId: string, maxWaitMs?: number, pollInterv
     video_height?: number;
     raw: object;
 }>;
+/**
+ * Returns the list of officially supported models for a given mode.
+ * @param {string} mode - 'text' | 'image' | 'first-last' | 'subject'
+ * @returns {string[]}
+ */
+export function getSupportedModelsForMode(mode: string): string[];
+/**
+ * Auto-detects the most likely mode based on provided options.
+ * @param {Object} options
+ * @returns {string} one of SUPPORTED_MODES
+ */
+export function detectMode(options?: Object): string;
+/**
+ * Validates that the chosen model is compatible with the detected/provided mode.
+ * Throws a clear, helpful error if not.
+ */
+export function validateModelForMode(model: any, mode: any, options?: {}): void;
+/**
+ * Checks if a string is a valid public HTTP/HTTPS URL.
+ * Rejects data: URLs, Base64, and non-HTTP schemes.
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isValidPublicUrl(str: string): boolean;
+/**
+ * Validates that an image reference is a public URL (rejects Base64).
+ * Throws a clear error if invalid.
+ * @param {string} fieldName - e.g. 'first_frame_image'
+ * @param {string} value
+ */
+export function validateImageUrl(fieldName: string, value: string): void;
+/**
+ * Validates subject_reference array for S2V-01.
+ * - Each reference must have `image` as an array of **exactly length 1**.
+ * - The single image must be a public HTTP/HTTPS URL (no Base64).
+ * Throws a clear, actionable error on any violation.
+ * @param {Array} subjectRef
+ */
+export function validateSubjectReference(subjectRef: any[]): void;

package/types/API/mureka/index.d.ts

@@ -0,0 +1,7 @@
+declare namespace _default {
+    export { music };
+    export { musicToolset };
+}
+export default _default;
+import * as music from './music.js';
+import musicToolset from './MusicToolset.js';