context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "url": "https://context7.com/sonilo-ai/sonilo-js",
  "public_key": "pk_h4BOrwVwv5CF9NJ5BIwvC",
  "projectTitle": "Sonilo JavaScript SDK",
  "description": "Official TypeScript/JavaScript client and CLI for the Sonilo API \u2014 generate music and sound effects from text or video.",
  "excludeFolders": [
    "**/dist/**",
    "**/node_modules/**",
    ".changeset"
  ],
  "excludeFiles": [
    "package-lock.json",
    "CHANGELOG.md"
  ],
  "rules": [
    "Read the API key from the SONILO_API_KEY environment variable by default; pass { apiKey } explicitly only when the caller has a reason to override it.",
    "text-to-music and video-to-music: use client.textToMusic.generate() / client.videoToMusic.generate() (streaming) for short synchronous tracks. The streaming path does NOT support outputFormat \"wav\", isolateVocals, preserveSpeech or ducking.",
    "For those options use submit() + client.tasks.wait() (async mode). isolateVocals/preserveSpeech/ducking apply to video-to-music only; text-to-music takes outputFormat alone.",
    "text-to-sfx and video-to-sfx are always async: submit() returns a task_id and generate() (or tasks.wait()) polls it to completion. Neither has a streaming variant.",
    "client.videoToSound and client.videoToVideoSound score one clip with a music bed AND sound effects in a single call \u2014 prefer them over chaining video-to-music with video-to-sfx, which is charged twice.",
    "Both sound endpoints are async-only and share params: musicPrompt, sfxPrompt (NOT a single prompt), segments, preserveSpeech, ducking. videoToSound returns mixed audio; videoToVideoSound returns the video with that track muxed in.",
    "A SoundResult's combined render is result.output_url (output_type says \"audio\" or \"video\"). music, music_processed and sfx are the individual stems; music_processed appears only when preserveSpeech or ducking altered the music bed.",
    "ducking is default-OFF server-side on every endpoint: leave it unset to keep the default, pass ducking: true to opt in. On videoToSound, ducking: true is also what pulls the source's own speech into the result at all.",
    "Result media (audio.url, or output_url for the sound endpoints) is a short-lived presigned URL on a different host, not the API's own domain. Download it with the SDK's download() helper or fetch().",
    "Never send the Authorization header to a presigned result URL.",
    "Catch AuthenticationError (401), PaymentRequiredError (402), RateLimitError (429, has retryAfter) and TaskFailedError (status \"failed\") separately rather than one generic branch \u2014 callers usually handle these differently.",
    "video / videoUrl accept exactly one of the two, never both and never neither \u2014 validate before constructing a request.",
    "Self-serve accounts start with free runs per endpoint (2 each for text-to-music, text-to-sfx, audio-ducking, video-analysis; 1 each for other video endpoints; none for dubbing), then bill normally. A first call succeeding is not proof billing works.",
    "Before a paid call, read (await client.account.services()).trial?.[service]?.remaining and degrade gracefully at 0: that call throws TrialExhaustedError (402 trial_exhausted), which no retry fixes \u2014 prompt for a payment method. trial may be absent.",
    "client.audioDucking ducks an EXISTING music bed under an EXISTING voice track; nothing is generated. One of voice/voiceUrl, one of music/musicUrl. Voice may be audio or video (video returns a new .mp4); music must be audio. Result: output_url, no stems.",
    "client.dubbing dubs one video into many languages in one async call. languages is an array of en, zh_cn, ja, ko, pt, pt_br, es, es_419, de, fr, it, ru, th, ar, tr, vi, id; omit for the default [\"zh_cn\",\"es\",\"fr\"]. Billed per language; no free trial runs.",
    "A DubbingResult has no audio/video/output_url. Its results live in result.outputs, a map of language code to dubbed .mp4 URL. dubbing's videoUrl must be https \u2014 plain http is rejected by the pipeline, not just discouraged.",
    "client.videoAnalysis returns a creative BRIEF, not media: the method is analyze() (not generate()) and VideoAnalysisResult has no download helper. Read result.segments (start/end/label/prompt) and result.variations[i].prompt.",
    "Pass a videoAnalysis variation's prompt straight to videoToMusic / videoToSfx / videoToSound as their prompt. It takes one of video/videoUrl plus optional prompt and variantsNum (1-5, billed per brief); max 360s of video, 10s billing floor.",
    "VideoAnalysisResult.segments and .variations are both OPTIONAL: a processing or failed poll carries neither. Guard with ?? [] before iterating rather than asserting them."
  ]
}