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

# Blob チャンクアップロードの開始

> このドキュメントでは、SquareCloud Blob API の POST /v1/objects/chunked エンドポイントの概要を包括的に説明します。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  アカウントの API キーです。これは[アカウント設定](https://squarecloud.app/ja/account/security)で確認できます。
</ParamField>

チャンクの開始 (Chunked Init) は、単一リクエストの上限である 100 MB を超えるファイルを最大 **1 GiB** までアップロードするためのフロー、チャンクアップロードを開始します。オブジェクトのキーを予約し、後続の 3 つの呼び出しで使い回す不透明な `upload` トークンを返します。各チャンクの送信には[チャンクの送信](/ja/blob-reference/endpoint/chunked-part)、オブジェクトの確定には[チャンクの完了](/ja/blob-reference/endpoint/chunked-complete)、キャンセルには[チャンクの中止](/ja/blob-reference/endpoint/chunked-abort)を使用します。

**サーバー側にセッションはありません**。トークンがアップロード状態のすべてなので、アップロードがページのリロードをまたぐ場合はトークンを永続化してください。トークンを失ったクライアントはアップロードをキャンセルできず、保存済みのチャンクは、サービスが回収するまで (約 24 時間) アカウントの上限である**同時 8 アップロード**にカウントされ続けます。

クエリの仕様は[オブジェクトのアップロード](/ja/blob-reference/endpoint/post)と同じで、`filename` が追加されています。ここには multipart のエンベロープがないため、保存される拡張子はクエリ文字列から取得する必要があります。アップロードには有料プランが必要です。

<ParamField query="name" type="string" placeholder="File Name" required>
  ファイル名を表す文字列。(拡張子なし)<br />a〜z、A〜Z、0〜9、および \_ のパターンに従う必要があります。(3〜32 文字)
</ParamField>

<ParamField query="filename" type="string" placeholder="Original filename">
  拡張子を含む元のファイル名 (例: `reads.fastq.gz`)。保存される拡張子はここから決定され、指定がない場合は `mime_type` パラメータ、次に `bin` にフォールバックします。
</ParamField>

<ParamField query="prefix" type="string" placeholder="File Prefix">
  ファイルのプレフィックスを表す文字列。<br />a〜z、A〜Z、0〜9、および \_ のパターンに従う必要があります。(3〜32 文字)
</ParamField>

<ParamField query="expire" type="number" placeholder="Expiration (days)">
  ファイルの有効期限を示す数値で、7〜1825 日 (5 年) の範囲で指定します。
</ParamField>

<ParamField query="security_hash" type="boolean" placeholder="Security Hash">
  security hash が必要な場合は true に設定します。
</ParamField>

<ParamField query="auto_download" type="boolean" placeholder="Auto Download">
  ファイルを自動ダウンロードに設定する場合は true に設定します。
</ParamField>

### 制限

<Note>
  * オブジェクトサイズ: 最大 **1 GiB** (1,073,741,824 バイト)。
  * チャンクサイズ: **最小 5 MB**、**最大 32 MB** (最後のチャンクはこれより小さくても構いません)。
  * オブジェクトあたりのチャンク数: **205** (パート番号は 1〜205)。
  * アカウントあたりのオープン中アップロード数: **8** 件まで同時 (`TOO_MANY_OPEN_UPLOADS`、429)。
  * レート制限: 10 秒あたり 5 回の開始。超過すると 10 秒間ブロックされます。

  制限値はハードコードせず、レスポンスの `chunk` オブジェクトから読み取ってください。
</Note>

### レスポンス

<ResponseField name="status" type="string">
  呼び出しが成功したかどうかを示します。成功した場合は "success"、失敗した場合は "error" です。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="オブジェクトを展開">
    <ResponseField name="upload" type="string">
      不透明なアップロードトークン。以降のフローのすべての呼び出しで使用します。このアップロードへの唯一のハンドルです。
    </ResponseField>

    <ResponseField name="id" type="string">
      オブジェクトが保存される ID (キー)。
    </ResponseField>

    <ResponseField name="name" type="string">
      ファイルの名前。
    </ResponseField>

    <ResponseField name="prefix" type="string">
      ファイルが保存されるプレフィックス (指定がなかった場合は `null`)。
    </ResponseField>

    <ResponseField name="url" type="string">
      完了後にオブジェクトが配信される公開 CDN URL。
    </ResponseField>

    <ResponseField name="chunk" type="object">
      チャンクフローの制限値: `min_size` と `max_size` (チャンクのバイト数)、`max_parts`、`max_object_size` (合計バイト数)。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    name: 'myfile',
    filename: 'reads.fastq.gz',
    expire: '30',
  });

  const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
    method: 'POST',
    headers: { Authorization: 'YOUR_API_KEY' },
  });

  const { response: upload } = await response.json();
  // persist upload.upload — it is the only handle to this upload
  ```

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

  response = requests.post(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'YOUR_API_KEY'},
      params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
  )
  upload = response.json()['response']
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
      "id": "3155597145698959364/myfile-ex30.fastq.gz",
      "name": "myfile",
      "prefix": null,
      "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
      "chunk": {
        "min_size": 5242880,
        "max_size": 33554432,
        "max_parts": 205,
        "max_object_size": 1073741824
      }
    }
  }
  ```
</ResponseExample>

### トラブルシューティング

<Tabs>
  <Tab title="400 ステータスコード">
    ### オブジェクト関連

    <CodeGroup>
      ```json NAME theme={null}
      // The provided object name is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_NAME"
      }
      ```

      ```json PREFIX theme={null}
      // The provided object prefix is invalid.
      // Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
      {
          "status": "error",
          "code": "INVALID_OBJECT_PREFIX"
      }
      ```

      ```json EXPIRE theme={null}
      // The provided expiration value for the object is invalid.
      // Must be a number ranging from 7 to 1825. (value in days).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json FILETYPE theme={null}
      // The file extension is malformed or too long.
      {
          "status": "error",
          "code": "INVALID_FILE_TYPE"
      }
      ```

      ```json BLOCKED_FILE_TYPE theme={null}
      // Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
      {
          "status": "error",
          "code": "BLOCKED_FILE_TYPE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="401 ステータスコード">
    ### 認証エラー

    <CodeGroup>
      ```json ACCESS_DENIED theme={null}
      // The API key is missing or invalid. Set a valid key in the Authorization header.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```

      ```json PERMISSION_DENIED theme={null}
      // The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
      {
          "status": "error",
          "code": "PERMISSION_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="403 ステータスコード">
    ### ストレージのクォータ超過

    <CodeGroup>
      ```json STORAGE_QUOTA_EXCEEDED theme={null}
      // You have exceeded your storage quota. Delete some files or upgrade your plan.
      {
          "status": "error",
          "code": "STORAGE_QUOTA_EXCEEDED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="429 ステータスコード">
    ### レート制限

    <CodeGroup>
      ```json RATE_LIMITED theme={null}
      // Init rate limit reached (5 opens per 10s window, blocked for 10s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```

      ```json TOO_MANY_OPEN_UPLOADS theme={null}
      // 8 chunked uploads already open. Complete or abort one first.
      {
          "status": "error",
          "code": "TOO_MANY_OPEN_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="500 ステータスコード">
    ### アップロード失敗

    <CodeGroup>
      ```json UPLOAD_FAILED theme={null}
      // Failed to open the chunked upload. Please try again later.
      {
          "status": "error",
          "code": "UPLOAD_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>