Blob Storage へのファイルアップロード

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

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

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

string

必須

アカウントの API キーです。これはアカウント設定で確認できます。

オブジェクトのアップロードは 1 つのファイルをアップロードし、その id と、公開ファイルの場合は埋め込みや直接共有に使える CDN の url を返します。プラットフォームでホストされているアプリケーションの添付ファイル、生成されたエクスポート、ユーザーがアップロードしたメディアを支えるエンドポイントです。 1 回のリクエストで受け付けるファイルは 512 バイトから 100 MB までです。それより大きい 10 GiB までのファイルは、チャンクアップロードのフローまたは S3 ゲートウェイを使用します。blob:write スコープ、または Authorization で送信されるアップロードトークンと、有効なプランが必要です。

返される id は不透明な値として扱ってください: 受け取ったまま保存し、他のルートにそのまま送り返します。pub/ または prv/ で始まり、ファイルの公開範囲や有効期限が変わると変化することがあります。2026年9月のアップデート以前に保存されたレガシーファイルは、この接頭辞のない id を保持し、すべてのルートが両方を受け付けます。

パラメーター

file

必須

FormData (multipart/form-data) を使用し、1 リクエストにつきファイルはちょうど 1 つです。
実際のファイル名を送信してください: 保存される拡張子はそこから取得されます (reads.fastq.gz は .fastq.gz のままです)。

string

必須

拡張子を除いたファイル名。1〜128 文字: 英字、数字、_、.、- を使用でき、英字、数字、_ のいずれかで始まる必要があります。.. を含めることはできません。

string

ファイルのフォルダーパス。/ で区切られた最大 8 セグメント、合計 256 文字までです。各セグメントは name と同じパターンに従い、最大 64 文字です。末尾の / は無視されます。

boolean

デフォルト:"false"

true にすると、公開 URL なしでファイルを保存します。オブジェクトのダウンロード、共有リンク、または S3 ゲートウェイを通じて読み取ります。省略した場合はプレフィックスのルールによって決まります。

string

この期間の経過後にファイルを自動的に削除します: 日数は 30 または 30d、時間は 6h です。1 時間から 1825 日 (5 年) まで指定できます。7 日未満の有効期限には Enterprise プランが必要です。省略した場合はプレフィックスのルールによって決まります。

boolean

デフォルト:"false"

true にすると名前にランダムな接尾辞が追加されるため、URL を推測されることがなく、新しいアップロードが古いファイルを置き換えることもありません。プライベートファイルには常に付与されます (private=true と一緒に false を指定すると拒否されます)。

boolean

デフォルト:"true"

セキュリティハッシュがない場合、同じ名前とプレフィックスでの新しいアップロードはファイルを置き換えます。false にすると、代わりに 409 OBJECT_ALREADY_EXISTS で拒否されます。

string

inline (ブラウザで開く) または attachment (元のファイル名でダウンロード)。

boolean

デフォルト:"false"

true にすると、ファイルの種類にかかわらず、ブラウザはファイルを開かずにダウンロードします。

string

CDN とブラウザがファイルを保持する期間: immutable (1 年)、N が 60〜31536000 秒の max-age=N、または no-cache (すべての読み取りがストレージに届きます。Enterprise のみ)。セキュリティハッシュ付きのファイルのデフォルトは immutable です。キャッシュがファイルの有効期限より長く残ることはありません。

string

文字列値からなる JSON オブジェクトで、オブジェクト情報で返されます。キーには a-z、0-9、- を使用します (最大 64 文字)。最大 5 キー、合計 512 バイトまでです。Pro と Enterprise のみ。

string

ファイルの SHA-256。一致しない場合、アップロードは CHECKSUM_MISMATCH で拒否され、何も保存されません。

レート制限と同時実行

各アカウントで同時に実行中にできるアップロードは最大 4 件です (TOO_MANY_CONCURRENT_UPLOADS、429)。
Hobby と Standard プランは 1 秒あたり 1 件のアップロードに制限されます (RATE_LIMITED、429)。Pro と Enterprise は対象外です。
アカウントに含まれるストレージを超えるアップロードは STORAGE_QUOTA_EXCEEDED で拒否されます。

ファイル形式

登録済みの MIME タイプがない形式 (.bam、.vcf、.fasta、.parquet、.h5、.npy など) を含め、事実上あらゆる拡張子を受け付けます。

配信される Content-Type は、拡張子からサーバー側で決定されます。不明な形式は application/octet-stream として配信されます。
ブラウザがレンダリングする形式 (.html、.svg、.xml など) は常にダウンロードとして配信されます。
実行ファイルとインストーラーは BLOCKED_FILE_TYPE で拒否されます: exe、msi、dll、bat、cmd、com、scr、cpl、pif、hta、vbs、vbe、jse、wsf、wsh、msc、reg、lnk、sys、drv、ps1、apk、xpi。
プレフィックスのルールまたはアップロードトークンで、受け付ける拡張子とサイズを制限できます。

レスポンス

string

成功した場合は “success”、失敗した場合は “error” です。

object

表示オブジェクトを切り替え

string

オブジェクトの id: pub/<user_id>/<path> または prv/<user_id>/<path>。不透明な値として扱ってください。

boolean

ファイルがプライベートかどうか。

string | null

公開 CDN URL (https://blob.squarecloud.dev/pub/...)。プライベートファイルの場合は null。

ISO 8601

ファイルが削除される日時。有効期限がある場合のみ含まれます。

number

ファイルサイズ (バイト)。

string

リクエストで送信された名前。

string

プレフィックス。送信された場合のみ含まれます。

string

保存されたファイルの SHA-256 (16 進数)。

boolean

アップロードが同じ名前の既存ファイルを置き換えた場合は true。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

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

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

エラー

コード	HTTP	発生する状況
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` または `prefix` がパターンに一致しない。
`INVALID_OBJECT_EXPIRE`	400	`expire` が 1 時間〜1825 日の期間ではない。
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	フラグが `true` または `false` ではない。
`INVALID_OBJECT_SECURITY_HASH`	400	ブール値ではない、またはプライベートファイルで `false` になっている。
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	値が受け付けられる形式の範囲外。
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	ファイルパートがない、拡張子の形式が正しくないかブロックされている、またはルールやトークンが許可していない。
`FILE_TOO_SMALL`	400	ファイルが 512 バイト未満。
`CHECKSUM_MISMATCH`	400	ファイルが `checksum_sha256` と一致しない。何も保存されていません。
`PERMISSION_DENIED`	401	アカウントに有効なプランがない。
`UPLOAD_TOKEN_USED`	401	アップロードトークンの使用回数が残っていない。期限切れのトークンは `ACCESS_DENIED` を返します。
`STORAGE_QUOTA_EXCEEDED`	403	アップロードすると含まれるストレージを超える。
`PREFIX_NOT_ALLOWED`	403	アップロードトークンが別のプレフィックスに紐付けられている。
`UPGRADE_REQUIRED`	403	オプションに上位のプランが必要。`message` でどのプランかが示されます。
`ACCOUNT_BLOCKED`	403	アカウントがファイルの保存をブロックされている。
`INVALID_CONTENT_TYPE`	409	リクエストが `multipart/form-data` ではない。
`OBJECT_ALREADY_EXISTS`	409	名前が存在し、`overwrite=false` である。
`FILE_TOO_LARGE`	413	100 MB を超えている、またはルールやトークンで許可されたサイズを超えている。
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	1 秒あたり 1 件のアップロード (Hobby と Standard)、または 4 件が実行中。
`UPLOAD_FAILED`	500	ストレージでエラーが発生した。再試行してください。
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	ストレージが一時的に利用できない。再試行してください。

完全な一覧はエラーを参照してください。

はじめに

オブジェクト

チャンクアップロード

アカウント

共有リンク

S3

Blob Storage へのファイルアップロード

パラメーター

レート制限と同時実行

ファイル形式

レスポンス

エラー

関連項目

​パラメーター

​レート制限と同時実行

​ファイル形式

​レスポンス

​エラー

​関連項目

パラメーター

レート制限と同時実行

ファイル形式

レスポンス

エラー

関連項目