# Start a focus session

Start a continuous focus session that streams crossfade-smooth music segments toward a target length. Returns `202 Accepted` with the created session, which begins generating segments immediately.

A focus session pre-generates short, crossfade-able segments up to `target_minutes`. Poll [Get a focus session](/docs/api-reference/music/get-focus-session) for ready segments and their playback URLs. Version 1 segments are crossfade-smooth (loudness + fade hints) rather than gapless.

## Path parameters

**`organization_id`** string required

The organization the session is scoped to. The caller must belong to it.

## Request Body

**`goal`** string required

The focus goal that steers the music. One of `focus`, `relax`, `sleep`, `energize`, or `custom_prompt`.

**`target_minutes`** integer required

Target total length of the session in minutes. Must be positive.

**`custom_prompt`** string optional

Free-text description of the desired music. Required when `goal` is `custom_prompt`; ignored otherwise.

**`intensity`** string optional · Defaults to `medium`

Energy level of the generated music. One of `low`, `medium`, or `high`.

**`divergence`** number optional · Defaults to `0.0`

How much each segment varies from the previous one, from `0.0` (very similar) to `1.0` (highly varied).

**`engine`** string optional

Internal engine key to generate with (from [List available music engines](/docs/api-reference/music/engines)). Defaults to a suitable enabled engine.

## Returns

A focus session object.

**`session_id`** string · Session id (`mfocus_`-prefixed).

**`status`** string · One of `active`, `ended`, or `stopped_cap` (stopped because the spend cap was reached).

**`goal`** string · The focus goal for the session.

**`engine`** string · Internal engine key the session generates with.

**`target_minutes`** integer · Target session length in minutes.

**`total_segments`** integer · Total number of segments planned for the session.

**`ready_count`** integer · Number of segments currently ready to play.

**`segments`** array · Ready segment objects. Each contains:

- **`segment_index`** integer · Zero-based position of the segment.
- **`playback_url`** string · Short-TTL signed URL for the segment audio.
- **`measured_duration_seconds`** number · Measured segment duration in seconds.
- **`target_lufs`** number · Target loudness (LUFS) for crossfade-smooth playback.
- **`fade_in_ms`** integer · Recommended fade-in duration in milliseconds.
- **`fade_out_ms`** integer · Recommended fade-out duration in milliseconds.


**`more_pending`** boolean · Whether more segments are still being generated.

**`next_ready_at`** string · Prefetch hint for when the next segment is expected to be ready (UTC), or `null`.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/music/org_abc123/focus/sessions" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "focus",
    "target_minutes": 60,
    "intensity": "medium",
    "divergence": 0.3
  }'
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

session = client.post(
    "/v1/music/org_abc123/focus/sessions",
    json={
        "goal": "focus",
        "target_minutes": 60,
        "intensity": "medium",
        "divergence": 0.3,
    },
)
print(session["session_id"], session["status"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/music/org_abc123/focus/sessions",
    headers={"X-API-Key": api_key},
    json={
        "goal": "focus",
        "target_minutes": 60,
        "intensity": "medium",
        "divergence": 0.3,
    },
)
print(response.json()["session_id"])
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/music/org_abc123/focus/sessions', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    goal: 'focus',
    target_minutes: 60,
    intensity: 'medium',
    divergence: 0.3,
  }),
});

const session = await response.json();
console.log(session.session_id, session.status);
```

**Response:**


```json 202 Accepted
{
  "session_id": "mfocus_7c2a9f4e1b8d",
  "status": "active",
  "goal": "focus",
  "engine": "studio",
  "target_minutes": 60,
  "total_segments": 30,
  "ready_count": 0,
  "segments": [],
  "more_pending": true,
  "next_ready_at": "2026-06-28T10:30:20Z"
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to access this resource.",
    "system_message": "USE_MUSIC_GENERATION capability required",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_def456uvw",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 422 Validation Error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters.",
    "system_message": "custom_prompt is required when goal is custom_prompt",
    "type": "validation_error",
    "status": 422,
    "details": { "field": "custom_prompt" },
    "trace_id": "req_ghi789rst",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [Get a focus session](/docs/api-reference/music/get-focus-session)
- [End a focus session](/docs/api-reference/music/end-focus-session)
- [Promote a focus segment](/docs/api-reference/music/promote-focus-segment)
- [List available music engines](/docs/api-reference/music/engines)