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

package/lib/API/stability.ai/audio-3.md

@@ -0,0 +1,205 @@
+# Stable Audio 3 API Specifications
+
+> Extracted from `lib/API/stability.ai/openapi.json` for Stable Audio 3.0 (`stable-audio-3` model).
+> This document serves as the source specification for generating the HTTP wrapper `audio.js` (similar to `lib/API/minimax/music.js` and associated `.md` files).
+
+## Overview
+
+**Stable Audio 3.0**: Fast, Best-Quality, Long-Form Music & Audio Generation
+
+Our most advanced audio generation model, capable of generating up to 6-minute, 44.1 kHz stereo compositions. Stable Audio 3.0 supports text-to-audio, audio-to-audio, and audio-inpaint workflows - allowing creators to upload a sound and transform it into new instruments, styles, or genres using natural language prompts. Ideal for music production, cinematic sound design, and remixing.
+
+- **Model ID**: `stable-audio-3`
+- **Credits**: Flat rate of 26 credits per successful generation (not charged for failed generations).
+- **Max Duration**: 380 seconds (default 190s)
+- **Output Formats**: `mp3` (default), `wav`
+- **Sample Rate**: 44.1 kHz stereo
+- **Base URL**: `https://api.stability.ai`
+- **Authentication**: Bearer token in `authorization` header (`Bearer sk-...`)
+- **Async Workflow**: All generation endpoints return HTTP 202 with a `generation_id`. Poll `GET /v2beta/audio/results/{id}` until 200 (audio ready) or error.
+- **Accept Header**: Use `audio/*` for direct binary audio response, or `application/json` for base64-encoded JSON.
+- **Notes**:
+  - No copyrighted content allowed.
+  - Max request size: 100MB for audio uploads.
+  - Audio input validation: 6 to 380 seconds.
+  - English is the only supported language (per error examples).
+  - See official docs: [Stable Audio 3.0 announcement](https://stability.ai/news/stable-audio-3-0)
+
+## Endpoints
+
+### 1. Text-to-Audio
+**POST** `/v2beta/audio/stable-audio/text-to-audio`
+
+Generates audio from a text prompt. No input audio required.
+
+#### Request
+- **Content-Type**: `multipart/form-data`
+- **Headers**:
+  - `authorization`: Bearer API key (required)
+  - `accept`: `audio/*` | `application/json` (optional, default `audio/*`)
+  - Other client headers optional (stability-client-id, etc.)
+
+#### Request Body Parameters (multipart/form-data)
+| Parameter     | Type    | Required | Default | Description |
+|---------------|---------|----------|---------|-------------|
+| `prompt`     | string | Yes     | -      | Strong, descriptive prompt defining instruments, moods, styles, genre. Max 10000 chars. |
+| `model`      | string | No      | `stable-audio-3` | Must be `stable-audio-3`. |
+| `duration`   | number | No      | 190    | Duration in seconds (1-380). |
+| `seed`       | number | No      | 0      | Random seed (0 for random, 0-4294967294). |
+| `steps`      | integer| No      | 8      | Sampling steps (4-8). |
+| `cfg_scale`  | number | No      | 1      | Prompt adherence (1-25). |
+| `output_format` | string | No   | `mp3`  | `mp3` or `wav`. |
+
+#### Responses
+- **202 Accepted**: `{ "id": "generation_id" }` - Poll results endpoint.
+- **400/422**: Validation or content errors (e.g., invalid params, copyrighted content, language issues).
+- **403**: Content moderation flag.
+- **429**: Rate limit.
+- **500**: Server error.
+
+#### Example (from OpenAPI)
+See code samples in openapi.json for Python, JS (axios + FormData), cURL.
+
+### 2. Audio-to-Audio
+**POST** `/v2beta/audio/stable-audio/audio-to-audio`
+
+Transforms an existing audio sample using a text prompt.
+
+#### Request
+- Same headers as Text-to-Audio.
+- **Required Files/Fields**: `audio` (binary file: mp3/wav, 6-380s).
+
+#### Request Body Parameters (multipart/form-data)
+| Parameter     | Type    | Required | Default | Description |
+|---------------|---------|----------|---------|-------------|
+| `prompt`     | string | Yes     | -      | Same as text-to-audio. |
+| `model`      | string | No      | `stable-audio-3` | `stable-audio-3`. |
+| `duration`   | number | No      | 190    | 1-380s. |
+| `seed`       | number | No      | 0      | 0-4294967294. |
+| `steps`      | integer| No      | 8      | 4-8. |
+| `cfg_scale`  | number | No      | 1      | 1-25. |
+| `output_format` | string | No   | `mp3`  | `mp3` or `wav`. |
+| `strength`   | number | No      | 1      | Denoising strength (0-1). 0 = identical to input, 1 = no audio influence. |
+| `audio`      | file   | Yes     | -      | Input audio file (mp3/wav). |
+
+#### Responses
+Same as Text-to-Audio (202 with id, errors, etc.).
+
+### 3. Inpaint
+**POST** `/v2beta/audio/stable-audio/inpaint`
+
+Inpaints/replaces a section of an audio sample using a text prompt and time mask.
+
+#### Request
+- Same headers.
+- **Required**: `audio` file + `prompt`.
+
+#### Request Body Parameters (multipart/form-data)
+| Parameter     | Type    | Required | Default | Description |
+|---------------|---------|----------|---------|-------------|
+| `prompt`     | string | Yes     | -      | Same as above. |
+| `model`      | string | No      | `stable-audio-3` | `stable-audio-3`. |
+| `duration`   | number | No      | 190    | 1-380s. |
+| `seed`       | number | No      | 0      | ... |
+| `steps`      | integer| No      | 8      | ... |
+| `cfg_scale`  | number | No      | 1      | ... |
+| `output_format` | string | No   | `mp3`  | ... |
+| `mask_start` | number | No      | 30     | Start time in seconds for inpaint segment (0-380). |
+| `mask_end`   | number | No      | 380    | End time in seconds (0-380). |
+| `audio`      | file   | Yes     | -      | Input audio file. |
+
+#### Responses
+Same as above.
+
+### 4. Fetch Audio Result
+**GET** `/v2beta/audio/results/{id}`
+
+Poll for generation result. Use after 202 from generation endpoints.
+
+#### Path Parameters
+- `id`: Generation ID from 202 response.
+
+#### Headers
+- `authorization`: Bearer key (required)
+- `accept`: `audio/*` (binary) or `application/json` (base64)
+
+#### Responses
+- **200 OK**:
+  - If `accept: audio/*`: Binary audio bytes + headers: `content-type`, `finish-reason: SUCCESS`, `seed`, `x-request-id`.
+  - If `accept: application/json`: JSON `{ "audio": "base64...", "seed": ..., "finish_reason": "SUCCESS" }`
+- **202**: Still in-progress: `{ "id": "...", "status": "in-progress" }`
+- **404**: Generation not found or expired.
+- Other errors as above.
+
+#### Polling Recommendation
+Poll every 5-10 seconds until 200 or error.
+
+## Common Error Responses
+- **400 Bad Request**: Invalid parameters.
+- **403 Forbidden**: Content moderation.
+- **422 Unprocessable**: Well-formed but rejected (e.g., copyrighted content, invalid language).
+- **429 Too Many Requests**: Rate limit exceeded.
+- **500 Internal Server Error**: Server issue.
+
+Error body example:
+```json
+{
+  "id": "error-id",
+  "name": "bad_request",
+  "errors": ["some-field: is required"]
+}
+```
+
+## OpenAPI Excerpts (Key Paths)
+
+### Text-to-Audio Path
+```json
+{
+  "post": {
+    "tags": ["Stable Audio"],
+    "summary": "Text-to-Audio",
+    "description": "Stable Audio transforms existing audio samples into new high-quality compositions up to six minutes long at 44.1kHz stereo using text instructions. ...",
+    "x-launchDarklyEnableFlag": "allow-access-stable-audio-3-api",
+    "requestBody": {
+      "content": {
+        "multipart/form-data": {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "prompt": { "type": "string", "maxLength": 10000, ... },
+              "model": { "type": "string", "enum": ["stable-audio-3"], "default": "stable-audio-3", ... },
+              "duration": { "type": "number", "minimum": 1, "maximum": 380, "default": 190, ... },
+              "seed": { ... },
+              "steps": { "type": "integer", "minimum": 4, "maximum": 8, "default": 8, ... },
+              "cfg_scale": { ... },
+              "output_format": { "type": "string", "enum": ["mp3", "wav"], "default": "mp3", ... }
+            },
+            "required": ["prompt"]
+          }
+        }
+      }
+    },
+    "responses": { "202": { ... }, "400": {...}, ... }
+  }
+}
+```
+
+(Similar structures for audio-to-audio with added `strength` and `audio` file; inpaint with `mask_start`, `mask_end`, `audio`; results as GET.)
+
+## Code Generation Notes for `audio.js`
+- Implement async methods: `textToAudio(params)`, `audioToAudio(params, audioFile)`, `inpaint(params, audioFile)`, `fetchResult(id, acceptHeader)`.
+- Use FormData for multipart uploads.
+- Handle 202 polling loop with timeout/retry.
+- Support both binary download and base64 JSON.
+- Add validation for duration (1-380), strength (0-1), masks, etc.
+- Error handling matching Minimax style (specific error messages, retries).
+- Default to `stable-audio-3` model, mp3 output.
+- Preserve compatibility with potential future stable-audio-2 if needed, but focus on v3.
+
+## References
+- Full OpenAPI: `lib/API/stability.ai/openapi.json`
+- Related: Stable Audio 2 endpoints exist under `/stable-audio-2/` (different model).
+- Official: https://platform.stability.ai/docs (or stableaudio.com)
+
+---
+*Generated on 2026-05-22. Specs extracted via jq from openapi.json paths: /v2beta/audio/stable-audio/* and /v2beta/audio/results/{id}.*