# ファイルの操作

リクエストに入力ファイルを添付する方法について説明します。1つのPDF、結合用の順序付きリスト、透かし用の2つ目の画像、それぞれの制限を扱います。

入力は `multipart/form-data` リクエストのバイナリパートとして送信します。ほとんどのアクションは `file` フィールドに1つの PDF だけを受け取りますが、2つのアクションはそれ以上を必要とします。結合はファイルの順序付き配列を受け取り、画像透かしは PDF に加えて2つ目のバイナリを受け取ります。このページでは、この3つの入力形式をすべて扱います。

## 単一ファイル

デフォルトの形式です。`file` フィールドに1つの PDF を添付し、アクションのオプションを文字列フィールドとして追加します：

```bash title="cURL"
curl https://api.pdfblocks.com/v1/extract_pages \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F pages='1..3' \
  -o extract.pdf
```

`-F file=@input.pdf` の `@` は、ファイルの内容を送信するよう cURL に指示します。単一入力を扱うすべてのアクション（透かし、セキュリティ、ページ操作、分割）はこの方式で動作します。

## 複数ファイル：結合

[ドキュメントを結合する](/docs/api/merge-pdf-documents)は、配列を受け付ける唯一のアクションです。`file` フィールドを**複数回**送信すると、ドキュメントはリクエスト内でパートが現れる順序で結合されます。少なくとも1つのファイルを指定してください。1回の呼び出しで多数のファイルを送ることもできます。

<Warning>
  順序は位置によって決まるため、結合したい順番でパートを送信してください。HTTP クライアントがフォームオブジェクトを公開している場合は、`file` を繰り返し指定したときに前のパートを上書きするのではなく追加されるように、*set* ではなく *append* メソッドを使用してください。
</Warning>

<CodeGroup>

```bash title="cURL"
curl https://api.pdfblocks.com/v1/merge_documents \
  -H 'X-API-Key: your_api_key' \
  -F file=@cover.pdf \
  -F file=@body.pdf \
  -F file=@appendix.pdf \
  -o merged.pdf
```

```python title="Python"
# pip install requests
import requests

files = [
    ('file', ('cover.pdf', open('cover.pdf', 'rb'), 'application/pdf')),
    ('file', ('body.pdf', open('body.pdf', 'rb'), 'application/pdf')),
    ('file', ('appendix.pdf', open('appendix.pdf', 'rb'), 'application/pdf')),
]

response = requests.post(
    'https://api.pdfblocks.com/v1/merge_documents',
    headers={'X-API-Key': 'your_api_key'},
    files=files,
)

response.raise_for_status()
with open('merged.pdf', 'wb') as output:
    output.write(response.content)
```

```javascript title="Node.js"
// Node.js 18+
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
for (const name of ['cover.pdf', 'body.pdf', 'appendix.pdf']) {
  body.append('file', new Blob([await readFile(name)]), name);
}

const response = await fetch('https://api.pdfblocks.com/v1/merge_documents', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('merged.pdf', Buffer.from(await response.arrayBuffer()));
```

</CodeGroup>

<Note>
  HTTP クライアントで `file` フィールドを繰り返すのが難しい場合（PHP の cURL や Ruby のフォームヘルパーなど）は、代わりに `file_1` から `file_10` までの番号付きフィールドを送信してください。これらは数値の順序で結合されます。10件を超えるドキュメントが必要な場合は、繰り返しの `file` 配列を使用してください。
</Note>

## PDF に添える画像：画像透かし

[画像透かしを追加する](/docs/api/add-image-watermark-to-pdf)は、`file` の PDF と `image` フィールドの透かし画像という、2つのバイナリパートを受け取ります。画像は **PNG または JPEG** である必要があります。どちらのパートも必須です。

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_image_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F image=@logo.png \
  -o watermarked.pdf
```

残りのフィールド（`transparency`、`margin`、`pages`）は通常の文字列オプションです。それぞれの範囲とデフォルト値については、アクションのリファレンスを参照してください。

## 受け付ける入力とサイズ

- `file` の入力（および結合される各ファイル）は、読み取り可能な PDF である必要があります。PDF として解析できないファイルは、`file` フィールドを示す `400` を返します。[エラー](/docs/api/errors)を参照してください。
- 画像透かしの `image` 入力は、PNG または JPEG である必要があります。
- アクションがどのページを対象にするかは、ファイルの添付方法とは別の話です。ページの選択は、[ページを選択する](/docs/api/selecting-pages)で説明している `pages` フィールドで指定してください。