> ## 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 エンドポイントの概要を包括的に説明します。

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

<ParamField body="file" type="file" placeholder="myphone.png" required>
  FormData を使用します。(multipart/form-data)
</ParamField>

<ParamField query="name" type="string" placeholder="File Name" required>
  ファイル名を表す文字列。(拡張子なし)<br />a〜z、A〜Z、0〜9、および \_ のパターンに従う必要があります。(3〜32 文字)
</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)">
  ファイルの有効期限を示す数値で、1〜365 日の範囲で指定します。
</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>
  アップロードには有料プランが必要です。

  * **Hobby** および **Standard** プランは **1 秒あたり 1 アップロード** に制限されています。
  * **Pro** および **Enterprise** プランは 1 秒あたりの制限を **受けません** — 代わりに最大 **4 件のアップロードを同時に** 実行できます。

  すべての有料プランを通じて、1 つのアカウントで同時に進行できるアップロードは最大 **4 件** です。4 件がまだ実行中の状態で別のアップロードを開始すると、`TOO_MANY_CONCURRENT_UPLOADS` (429) が返されます。
</Note>

<Info>
  セキュリティのため、`.html` および `.svg` ファイルは常にダウンロードとして配信され (`application/octet-stream` として提供)、インラインでレンダリングされません。
</Info>

### レスポンス

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

<ResponseField name="response" type="object">
  <Expandable title="オブジェクトを展開">
    <ResponseField name="id" type="string">
      アップロードされたファイルの ID。
    </ResponseField>

    <ResponseField name="name" type="string">
      アップロードされたファイルの名前。
    </ResponseField>

    <ResponseField name="prefix" type="string">
      ファイルが保存されたプレフィックス (`prefix` クエリの内容をそのまま返します。指定がなかった場合は省略されます)。
    </ResponseField>

    <ResponseField name="size" type="number">
      アップロードされたファイルのサイズ (バイト単位)。
    </ResponseField>

    <ResponseField name="url" type="string">
      アップロードされたファイルの URL。(Square Cloud CDN で配信されるファイル)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
    --header 'Authorization: YOUR_API_KEY' \
    --form 'file=@./myphone.png'
  ```

  ```javascript JavaScript theme={null}
  import fs from 'node:fs';

  const form = new FormData();
  form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

  const params = new URLSearchParams({
    name: 'myfile',
    prefix: 'images',
    expire: '30',
  });

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

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

  with open('myphone.png', 'rb') as f:
      response = requests.post(
          'https://blob.squarecloud.app/v1/objects',
          headers={'Authorization': 'YOUR_API_KEY'},
          params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
          files={'file': ('myphone.png', f, 'image/png')},
      )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
      "status": "success",
      "response": {
          "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
          "name": "test",
          "prefix": "images",
          "size": 416230,
          "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
      }
  }
  ```
</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 1 to 365. (value in days).
      {
          "status": "error",
          "code": "INVALID_OBJECT_EXPIRE"
      }
      ```

      ```json SECURITY_HASH theme={null}
      // The provided security hash boolean is invalid.
      // Just set to true or false. 😅
      {
          "status": "error",
          "code": "INVALID_OBJECT_SECURITY_HASH"
      }
      ```

      ```json AUTO_DOWNLOAD theme={null}
      // The provided auto-download boolean is invalid.
      // Just set to true or false. 😅
      {
          "status": "error",
          "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
      }
      ```
    </CodeGroup>

    ### ファイル関連

    <Info>現在の最大ファイルサイズは 100MB です。将来的には 10GB まで引き上げる予定です。現時点では、技術的な制約と負荷分散の都合により、上限は 100MB となっています。</Info>

    <CodeGroup>
      ```json INVALID_FILE theme={null}
      // The provided file is invalid.
      {
          "status": "error",
          "code": "INVALID_FILE"
      }
      ```

      ```json FILETYPE theme={null}
      // The provided file type is invalid.
      {
          "status": "error",
          "code": "INVALID_FILETYPE"
      }
      ```

      ```json FILE_TOO_SMALL theme={null}
      // The file size is too small (< 1kb).
      {
          "status": "error",
          "code": "FILE_TOO_SMALL"
      }
      ```
    </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.
      // Also returned when the account is on the free plan — uploading requires a paid plan.
      {
          "status": "error",
          "code": "ACCESS_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="409 ステータスコード">
    ### 無効なコンテンツタイプ

    <CodeGroup>
      ```json INVALID_CONTENT_TYPE theme={null}
      // This route only accepts multipart/form-data requests.
      {
          "status": "error",
          "code": "INVALID_CONTENT_TYPE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="413 ステータスコード">
    ### ペイロードが大きすぎます

    <Info>現在の最大ファイルサイズは 100MB です。</Info>

    <CodeGroup>
      ```json PAYLOAD_TOO_LARGE theme={null}
      // The uploaded file exceeds the maximum allowed size of 100 MB.
      {
          "status": "error",
          "code": "PAYLOAD_TOO_LARGE"
      }
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```json RATELIMIT theme={null}
      // Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
      {
          "status": "error",
          "code": "RATELIMIT"
      }
      ```

      ```json TOO_MANY_CONCURRENT_UPLOADS theme={null}
      // Too many simultaneous uploads (max 4 in progress at a time per account).
      {
          "status": "error",
          "code": "TOO_MANY_CONCURRENT_UPLOADS"
      }
      ```
    </CodeGroup>
  </Tab>

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

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