 Server : Apache/2 System : Linux server-15-235-50-60 5.15.0-164-generic #174-Ubuntu SMP Fri Nov 14 20:25:16 UTC 2025 x86_64 User : gositeme ( 1004) PHP Version : 8.2.29 Disable Function : exec,system,passthru,shell_exec,proc_close,proc_open,dl,popen,show_source,posix_kill,posix_mkfifo,posix_getpwuid,posix_setpgid,posix_setsid,posix_setuid,posix_setgid,posix_seteuid,posix_setegid,posix_uname Directory : /home/gositeme/domains/soundstudiopro.com/private_html/ |
# API.box Documentation Review & Findings
## Based on Official Documentation & Log Analysis
### API Endpoint Specifications
**Endpoint**: `POST https://api.api.box/api/v1/generate`
**Required Headers**:
- `Authorization: Bearer YOUR_API_KEY`
- `Content-Type: application/json`
### Request Parameters
#### Custom Mode Requirements (from docs):
- **If `customMode: true`**:
- **If `instrumental: true`**: `style` and `title` are **REQUIRED**
- **If `instrumental: false`**: `style`, `prompt`, and `title` are **REQUIRED**
- **Character Limits**:
- V3_5 & V4: `prompt` up to 3000 chars, `style` up to 200 chars
- V4_5 & V4_5PLUS: `prompt` up to 5000 chars, `style` up to 1000 chars
- **Title**: Max 80 characters
- **If `customMode: false`**:
- Only `prompt` is required
- **Prompt limit**: 400 characters max
- Other parameters should be left empty
### Issues Found in Logs
#### 1. **customMode Being Sent as "false"**
**Problem**: Logs show `"customMode": "false"` even though form has `value="true"`
**Example from log**:
```json
{
"customMode": "false",
"duration": 180,
"style": "Pop"
}
```
**Root Cause**: Need to verify form submission is correctly reading the hidden field
**Fix**: Ensure JavaScript is updating the hidden field before submission
#### 2. **Duration is 180 seconds (3 minutes) instead of 360 (6 minutes)**
**Problem**: Duration being sent is 180 seconds, not the expected 360
**Example from log**:
```json
{
"duration": 180 // Should be 360
}
```
**Root Cause**: The duration select field might not be syncing to hidden field, or default is wrong
**Fix**: Verify `updateFormFields()` is syncing duration correctly
#### 3. **Style Still Being Sent as "Pop"**
**Problem**: Even after our fix, logs show `"style": "Pop"` being sent
**Example from log**:
```json
{
"style": "Pop", // Should not be sent if genre is empty
"title": ""
}
```
**Root Cause**: Old code path or genre is being set somewhere
**Fix**: Check if genre is being set from prompt parsing or defaults
#### 4. **Empty Title Being Sent**
**Problem**: `"title": ""` is being sent instead of omitting the field
**Example from log**:
```json
{
"title": "" // Should not be in request at all
}
```
**Root Cause**: Our code adds title even if empty
**Fix**: Only add title to `$api_data` if not empty (already fixed, but verify)
### Callback Format (Actual Structure from Logs)
The API sends callbacks in this format:
```json
{
"code": 200,
"msg": "Text generated successfully." | "First audio generated successfully." | "All generated successfully.",
"data": {
"callbackType": "text" | "first" | "complete",
"task_id": "29b545cf11a7dbcf34836a1f1c5f3ed9",
"data": [
{
"id": "2db928dc-50a7-4dd8-81e1-d8f7e6b01b3f",
"audio_url": "https://apiboxfiles.erweima.ai/...mp3", // Empty in "text", populated in "complete"
"duration": 192.8, // In seconds, only in "complete"
"title": "Feel the Beat",
"tags": "heavy bass, synth melodies, electronic dance...",
"prompt": "[Verse]...", // Generated lyrics
"model_name": "chirp-v4",
"image_url": "https://apiboxfiles.erweima.ai/...jpeg",
"source_audio_url": "https://cdn1.suno.ai/...mp3",
"stream_audio_url": "https://mfile.erweima.ai/...",
"createTime": 1753324583536
},
{
// Second variation...
}
]
}
}
```
### Callback Stages
1. **`callbackType: "text"`** - Lyrics/text generated, no audio yet
2. **`callbackType: "first"`** - First variation audio ready
3. **`callbackType: "complete"`** - All variations complete
### Duration Observations
From callback logs:
- Track 1: `duration: 192.8` seconds (3.2 minutes) - requested 180 seconds
- Track 2: `duration: 104.52` seconds (1.7 minutes) - requested 180 seconds
**Finding**: API is generating tracks close to requested duration, but sometimes shorter. For 5-7 minute tracks, we need to request 300-420 seconds.
### Model Name in Callbacks
Callbacks return `"model_name": "chirp-v4"` regardless of what we send. This suggests:
- API might normalize model names
- Or V5 maps to "chirp-v4" internally
### Required Fixes
1. ✅ **customMode**: Ensure it's always "true" (already set in form, but verify submission)
2. ✅ **Duration**: Fix sync between select and hidden field (already fixed in updateFormFields)
3. ✅ **Style**: Extract from prompt or use fallback when customMode=true (REQUIRED by API)
4. ✅ **Title**: Generate from prompt when customMode=true (REQUIRED by API)
5. ✅ **Non-Custom Mode**: Explicitly unset style and title (API requires empty params)
### Critical API Requirements (from docs)
**When `customMode: true`**:
- **If `instrumental: true`**: `style` and `title` are **REQUIRED**
- **If `instrumental: false`**: `style`, `prompt`, and `title` are **REQUIRED**
**When `customMode: false`**:
- Only `prompt` is required
- Other parameters should be **left empty** (not sent)
### Solution Implemented
1. **Genre/Style Extraction**: When customMode=true and no genre provided:
- Extract from prompt using "Style:" prefix or genre keywords
- Fallback to "Electronic" (API requires style in custom mode)
2. **Title Generation**: When customMode=true and no title provided:
- Generate from first 77 chars of prompt
- Clean up common prefixes
- Fallback to "Generated Track"
3. **Non-Custom Mode**: Explicitly unset style and title to ensure they're not sent
### Testing Checklist
- [ ] Create track with customMode=true, verify it's sent correctly
- [ ] Create track with 360 second duration, verify it's sent correctly
- [ ] Create track without genre, verify style is NOT sent
- [ ] Create track without title, verify title is NOT sent
- [ ] Verify callback receives and processes all 3 stages (text, first, complete)
- [ ] Verify variations are stored correctly
- [ ] Verify duration in callback matches request (or is close)