# Save generation to history

- **Method:** `POST`
- **Path:** `/api/v1/history`
- **Operation ID:** `save_to_history_api_v1_history_post`
- **Tags:** History

Persist a generation result (audio + metadata) to the history library.

## Effective servers

- `http://127.0.0.1:8100`

  Voice Creator Pro on this computer

## Request body

**Required:** `true`

**Content type:** `application/json`

schema: `SaveHistoryRequest`

- **`audio_base64` (required)**: `string`

  Base64-encoded audio (WAV)
- **`mode` (required)**: `string`

  Generation mode: 'clone', 'design', or 'tts'
- **`target_text` (required)**: `string`

  Text that was generated
- **`extra_metadata`**: `object | null`

  Additional metadata

**Example:**

```json
{
  "audio_base64": "UklGRi4AAABXQVZFZm10IBAAAA...",
  "target_text": "Welcome to our application.",
  "mode": "clone",
  "extra_metadata": {
    "additionalProperty": "anything"
  }
}
```

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `HistorySaveResponse`

- **`success` (required)**: `boolean`

  Whether the history item was saved successfully
- **`item`**: `object | null`, schema: `HistoryItem`

  Saved history item metadata
  - **`created_at` (required)**: `string`

    ISO 8601 creation timestamp
  - **`duration_seconds` (required)**: `number`

    Audio duration in seconds
  - **`file_size` (required)**: `integer`

    Audio file size in bytes
  - **`full_text` (required)**: `string`

    Full generated text
  - **`id` (required)**: `string`

    Unique history item identifier
  - **`mode` (required)**: `string`

    Generation mode used (clone, design, tts)
  - **`text` (required)**: `string`

    Truncated generated text (for display)
  - **`design_id`**: `string | null`

    Design voice ID (design mode)
  - **`design_name`**: `string | null`

    Design voice name (design mode)
  - **`instruct_text`**: `string | null`

    Voice description (design mode)
  - **`ref_text`**: `string | null`

    Reference text (clone mode)
  - **`speaker`**: `string | null`

    Speaker ID (tts mode)
  - **`speaker_name`**: `string | null`

    Speaker name (tts mode)
  - **`voice_id`**: `string | null`

    Voice ID used (clone mode)
  - **`voice_name`**: `string | null`

    Voice name used (clone mode)
- **`message`**: `string | null`

  Error message if save failed

**Example:**

```json
{
  "success": true,
  "item": {
    "id": "h1b2c3d4",
    "text": "Welcome to our...",
    "full_text": "Welcome to our application.",
    "mode": "clone",
    "created_at": "2026-01-15T10:30:00Z",
    "duration_seconds": 3.2,
    "file_size": 102400,
    "ref_text": "",
    "voice_id": "",
    "voice_name": "",
    "instruct_text": "",
    "design_id": "",
    "design_name": "",
    "speaker": "",
    "speaker_name": "",
    "additionalProperty": "anything"
  },
  "message": ""
}
```

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

## Schemas

- `HTTPValidationError` — shown above.
- `HistoryItem` — shown above.
- `HistorySaveResponse` — shown above.
- `SaveHistoryRequest` — shown above.
- `ValidationError` — shown above.