> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 音声をアップロード

> MP3・WAV・M4A をアップロードし、生成 API 用の公開 URL を取得します。既定の上限は 1 ファイル 15MB。

> [!NOTE]
>
> 参照素材をアップロードすると、成功時に公開 URL が直接返ります。ポーリングは不要です。アップロードは無料ですが、アカウント残高は 0 より大きい必要があります。3 つのアップロード API はユーザー単位の枠を共有し、既定では 72 時間に合計 2000 ファイルまでです。

> [!NOTE]
>
> ドキュメントの Playground はファイルアップロードに対応していません。以下の cURL・Python・JavaScript 例を使用してください。JavaScript 例には、ファイルを選択済みの `<input type="file">` が必要です。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/uploads/audios \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@/path/to/reference.mp3'
```

```python Python theme={null}
import requests

with open("reference.mp3", "rb") as file:
    response = requests.post(
        "https://api.apimart.ai/v1/uploads/audios",
        headers={"Authorization": "Bearer <token>"},
        files={"file": file}
    )

response.raise_for_status()
result = response.json()
print(result["url"])
```

```javascript JavaScript theme={null}
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");

const formData = new FormData();
formData.append("file", file, file.name);

const response = await fetch("https://api.apimart.ai/v1/uploads/audios", {
  method: "POST",
  headers: { Authorization: "Bearer <token>" },
  body: formData
});
const result = await response.json();
if (!response.ok) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
```

```json 200 theme={null}
{
  "url": "https://cdn.example/uploads/reference.mp3",
  "filename": "reference.mp3",
  "content_type": "audio/mpeg",
  "file_type": "audio",
  "bytes": 235680,
  "created_at": 1793836800,
  "quota": {
    "limit": 2000,
    "used": 124,
    "remaining": 1876,
    "window_hours": 72,
    "reset_at": 1794063600
  }
}
```

```json 402 theme={null}
{
  "error": {
    "message": "insufficient balance: uploading files requires a positive account balance, please top up",
    "type": "insufficient_user_quota"
  }
}
```

```json 413 theme={null}
{
  "error": {
    "message": "audio file exceeds maximum 15728640 bytes (15MB)",
    "type": "invalid_request_error"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "param": ""
  },
  "quota": {
    "limit": 2000,
    "used": 2000,
    "remaining": 0,
    "window_hours": 72,
    "reset_at": 1794063600
  }
}
```

## 認証

**Authorization** `string` *required*

有効で、無効化・期限切れでない APIMart API Key を `Bearer <token>` として指定します。アカウントが停止されておらず、残高が正である必要があります。Key 自体の利用枠を使い切っていてもアップロードできます。Key は [API Key 管理](https://apimart.ai/keys) で取得できます。

## リクエストパラメータ

**file** `file` *required*

`multipart/form-data` の `file` フィールドに、ファイル名付きで 1 ファイルを送信します。JSON、base64 文字列、ファイル URL で置き換えないでください。他のフォームフィールドは無視され、複数の `file` を送信した場合は最初の 1 件のみ処理されます。

**対応形式：** MP3 (.mp3), WAV (.wav), M4A (.m4a)

**既定のファイルサイズ上限：** 15MB。サイズ上限は設定により変更されます。実際の設定と上限超過エラーの値を確認してください。

cURL の `--form`、Python の `files`、JavaScript の `FormData` では、boundary を含む `Content-Type` をクライアントに生成させてください。手動で指定しないでください。

## ファイル検証

形式は拡張子やクライアント指定の MIME 型ではなく、内容から判定します。内容は送信先 API の種類と一致する必要があります。拡張子の変更は形式変換にはならず、不一致は HTTP `400` になります。

音声のコンテナまたはフレーム構造を検証し、偽装ヘッダーや破損ファイルを拒否します。OGG、FLAC、AAC（ADTS 生ストリーム）は非対応です。

| 形式 | 検出される MIME 型 |
| - | - |
| MP3 (.mp3) | `audio/mpeg` |
| WAV (.wav) | `audio/wav` |
| M4A (.m4a) | `audio/mp4` |

## 成功レスポンス

HTTP `200` でファイル情報を返します。`url` は JSON の最上位にあり、`data` によるラップや生成タスク ID はありません。

**url** `string`

ファイルの公開 URL。生成 API の対応する参照素材パラメータに渡します。モデルごとに形式・サイズ・数量・時間の制限があるため、アップロード成功だけでは利用できる保証はありません。

**filename** `string`

元のファイル名。

**content\_type** `string`

ファイル内容からサーバーが検出した MIME 型。クライアントの申告値ではありません。

**file\_type** `string`

ファイル種別。この API は `audio` を返します。

**bytes** `integer`

実際のファイルサイズ（バイト）。

**created\_at** `integer`

アップロード時刻（Unix 秒）。

**quota** `object`

任意のアップロード枠情報。制限がある場合のフィールドは下表のとおりです。無制限や統計の一時取得不可の場合は構造が異なります。

| フィールド | 説明 |
| - | - |
| `quota.limit` | ユーザーが期間内に成功させられるアップロード数の上限。既定の 2000 と異なる場合があります。 |
| `quota.used` | 今回の成功分を含む、期間内の使用数。 |
| `quota.remaining` | 現在追加でアップロードできるファイル数。 |
| `quota.window_hours` | 統計期間の時間数。既定は 72。 |
| `quota.reset_at` | 最も古い一群が期間外になる時刻（Unix 秒）。一部の枠が空く時刻であり、全枠が一度にリセットされるとは限りません。 |

## 共有枠とリクエスト制限

画像・動画・音声で同じユーザー枠を共有します。同一ユーザーの Key を増やしても枠は増えません。毎正時に期間が移動し、既定では直近約 71–72 時間の成功分を数えます。形式不正、サイズ超過、保存失敗はファイル枠を消費しません。

通常の制限付きレスポンスには `X-Upload-Quota-Limit`、`X-Upload-Quota-Remaining`、`X-Upload-Quota-Reset` が付き、それぞれ `limit`、`remaining`、`reset_at` に対応します。Reset は Unix 秒です。

無制限の場合は `quota: {"unlimited": true}` を返し、上記 3 ヘッダーは付きません。統計を一時取得できない場合、成功レスポンスでも `quota` を省略することがあります。欠落を 0 や無制限と解釈したり、それだけを理由に再アップロードしたりしないでください。

ファイル枠を使い切ると HTTP `429`、`error.type: rate_limit_exceeded`、`quota`（`remaining: 0`）、`Retry-After` を返します。指定秒数待って再試行してください。別途、Key ごとに 60 秒間 1000 リクエストの制限があり、こちらは `rate_limit_error` です。

## エラー処理

エラーは JSON 最上位の `error` オブジェクトです。HTTP ステータス、`error.type` / `error.code`、`error.message` を確認してください。

| HTTP | `error.type` | 原因と対応 |
| - | - | - |
| 400 | `invalid_request_error` | ファイル欠落、multipart 以外、空ファイル、種類不一致、非対応形式、内容破損。ファイルまたは送信先を修正してください。 |
| 401 / 403 | `—` | Key が無効・無効化済み、またはアカウント停止。認証とアカウント状態を確認してください。 |
| 402 | `insufficient_user_quota` | 残高が 0 以下、または Key の期限切れ。入金するか有効な Key を使用してください。無料アップロードでも利用条件を満たす必要があります。 |
| 413 | `invalid_request_error` | 種類別のサイズ上限超過。圧縮・縮小し、エラーにある現在の上限を確認してください。 |
| 429 | `rate_limit_exceeded` | ユーザー共有枠を使い切りました。`quota` と `Retry-After` を読み、枠が空くまで待ってください。 |
| 429 | `rate_limit_error` | Key のリクエスト頻度が高すぎます。頻度を下げ、間隔を空けて再試行してください。 |
| 503 | `server_error` | 動画・音声の同時アップロード過多、またはストレージの一時停止。後で再試行してください。 |
| 500 | `server_error` | ストレージへの保存失敗。後で再試行してください。 |

## URL とファイルの保存

72 時間は既定の統計期間であり、ファイル保存期間の保証ではありません。保持期間はストレージのポリシーに従います。元ファイルを保管し、URL は早めに生成に使用してください。永続 URL とは限りません。

## 他のアップロード API

* [画像をアップロード](https://docs.apimart.ai/ja/api-reference/uploads/images.md)
* [動画をアップロード](https://docs.apimart.ai/ja/api-reference/uploads/videos.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.