# レスポンスフォーマットとコンテンツネゴシエーション

アクションから返ってくるもの、そして `Accept` ヘッダーが PDF、ZIP、JSON エンベロープ、multipart/mixed のどれを選ぶかについて説明します。

ほとんどのアクションは単一の `application/pdf` ドキュメントを返します。4つの分割アクションは一度に複数のドキュメントを返し、その梱包方法を `Accept` リクエストヘッダーで選びます。このページは、そのコンテンツネゴシエーションのリファレンスです。梱包オプション、JSON エンベロープのスキーマ、そして `Accept` ヘッダーが何にも一致しない場合に何が起きるかを説明します。

## 単一ドキュメントのレスポンス

分割ではないすべてのアクションは `200 OK` で応答し、処理済みの PDF を生の本文として返します。

```http
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 48213
```

ネゴシエーションの余地はありません。各アクションページの例のように、本文をファイルへストリーミングしてください。

## 複数ドキュメントのレスポンス

分割系のアクションは、1回の呼び出しから複数のドキュメントを返します。[ページ数で分割する](/docs/api/split-pdf-by-page-count)、[指定したページで分割する](/docs/api/split-pdf-at-page)、[ファイルサイズで分割する](/docs/api/split-pdf-by-file-size)、[ページグループで分割する](/docs/api/split-pdf-into-page-groups) です。出力ドキュメントは、順番に `00001.pdf`、`00002.pdf` のように名付けられます。梱包方法は `Accept` リクエストヘッダーで選びます。

| `Accept` ヘッダー      | レスポンス                                                        |
| -------------------- | -------------------------------------------------------------- |
| *(送信なし)*        | `application/zip`（デフォルト）                                 |
| `application/zip`    | 出力 PDF の ZIP アーカイブ                               |
| `application/json`   | base64 エンコードされたドキュメントの JSON エンベロープ                    |
| `multipart/mixed`    | ドキュメントごとに1パート                                              |
| それ以外        | `406 Not Acceptable`                                            |

### application/zip：デフォルト

`Accept` ヘッダーを送らない場合（または `Accept: application/zip` を送った場合）、レスポンスは `00001.pdf`、`00002.pdf` のように名付けられたエントリを持つ ZIP アーカイブになります。

```bash title="cURL"
curl https://api.pdfblocks.com/v1/split_by_page_count \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F page_count=10 \
  -o parts.zip
```

`parts.zip` を展開すると、個々のドキュメントが得られます。

### application/json：base64 エンベロープ

`Accept: application/json` をリクエストすると、すべてのドキュメントが1つの JSON レスポンスにインラインで含まれます。パートをメモリに保持したい場合や、ファイルシステムに触れずに転送したい場合に便利です。

```bash title="cURL"
curl https://api.pdfblocks.com/v1/split_by_page_count \
  -H 'X-API-Key: your_api_key' \
  -H 'Accept: application/json' \
  -F file=@input.pdf \
  -F page_count=10 \
  -o parts.json
```

本文は `documents` 配列で、各エントリが名前と base64 エンコードされたバイト列を持ちます。

```json
{
  "documents": [
    {
      "name": "00001.pdf",
      "content": "JVBERi0xLjcKJeLjz9MK... (base64)",
      "content_type": "application/pdf"
    },
    {
      "name": "00002.pdf",
      "content": "JVBERi0xLjcKJeLjz9MK... (base64)",
      "content_type": "application/pdf"
    }
  ]
}
```

<ParamField name="documents" type="array" required>
  出力 PDF ドキュメント（順序どおり）。
</ParamField>

<ParamField name="documents[].name" type="string" required>
  ドキュメント名：`00001.pdf`、`00002.pdf` など。
</ParamField>

<ParamField name="documents[].content" type="string (base64)" required>
  base64 エンコードされた PDF ドキュメント。デコードすると生の PDF バイト列が復元されます。
</ParamField>

<ParamField name="documents[].content_type" type="string" required>
  ドキュメントのメディアタイプ：`application/pdf`。
</ParamField>

### multipart/mixed：ドキュメントごとに1パート

`Accept: multipart/mixed` をリクエストすると、出力 PDF ごとに1パートを持つ multipart 本文として、ドキュメントが順番にストリーミングされます。各パートの `Content-Type` は `application/pdf` で、`Content-Disposition` には `00001.pdf`、`00002.pdf` のように名前が付けられます。

```bash title="cURL"
curl https://api.pdfblocks.com/v1/split_by_page_count \
  -H 'X-API-Key: your_api_key' \
  -H 'Accept: multipart/mixed' \
  -F file=@input.pdf \
  -F page_count=10 \
  -o parts.multipart
```

## 一致しない `Accept` は `406` を返す

上記の3つの形式のどれにも一致しない `Accept` ヘッダーを送った場合（例えば分割アクションに対して `Accept: application/pdf` を送った場合）、API は `406 Not Acceptable` と `application/problem+json` 本文で応答します。`Accept` を省略してデフォルトの ZIP を使うか、サポートされているメディアタイプのいずれかをリクエストしてください。problem details の形については [エラー](/docs/api/errors) を参照してください。

<Tip>
  分割アクションを呼び出し、各フォーマット（ZIP の展開、JSON エンベロープのデコード、multipart パートの読み取り）を処理するエンドツーエンドのコードについては、[PDF を分割して出力を扱う](/docs/api/splitting-a-pdf) ガイドを参照してください。
</Tip>