Blob オブジェクトのアップロード

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'

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,
});

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')},
    )

{
    "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"
    }
}

Authorization

string

必須

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

file

必須

FormData を使用します。(multipart/form-data)

name

string

必須

ファイル名を表す文字列。(拡張子なし)
a〜z、A〜Z、0〜9、および _ のパターンに従う必要があります。(3〜32 文字)

prefix

string

ファイルのプレフィックスを表す文字列。
a〜z、A〜Z、0〜9、および _ のパターンに従う必要があります。(3〜32 文字)

expire

number

ファイルの有効期限を示す数値で、1〜365 日の範囲で指定します。

security_hash

boolean

security hash が必要な場合は true に設定します。

auto_download

boolean

ファイルを自動ダウンロードに設定する場合は true に設定します。

レート制限と同時実行数

アップロードには有料プランが必要です。

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

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

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

レスポンス

status

string

呼び出しが成功したかどうかを示します。成功した場合は “success”、失敗した場合は “error” です。

response

object

表示オブジェクトを展開

string

アップロードされたファイルの ID。

name

string

アップロードされたファイルの名前。

prefix

string

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

size

number

アップロードされたファイルのサイズ (バイト単位)。

url

string

アップロードされたファイルの URL。(Square Cloud CDN で配信されるファイル)

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'

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,
});

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')},
    )

{
    "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"
    }
}

トラブルシューティング

オブジェクト関連

// 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"
}

// 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"
}

// 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"
}

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

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

ファイル関連

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

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// The provided file type is invalid.
{
    "status": "error",
    "code": "INVALID_FILETYPE"
}

// The file size is too small (< 1kb).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

認証エラー

// 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"
}

ストレージのクォータ超過

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

無効なコンテンツタイプ

// This route only accepts multipart/form-data requests.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

ペイロードが大きすぎます

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

// The uploaded file exceeds the maximum allowed size of 100 MB.
{
    "status": "error",
    "code": "PAYLOAD_TOO_LARGE"
}

レート制限

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATELIMIT"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

アップロード失敗

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

オブジェクトの削除このドキュメントは、SquareCloud Blob API の DELETE /v1/objects エンドポイントの包括的な概要を提供します。

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'

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,
});

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')},
    )

{
    "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"
    }
}

​レート制限と同時実行数

​レスポンス

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

​オブジェクト関連

​ファイル関連

​認証エラー

​ストレージのクォータ超過

​無効なコンテンツタイプ

​ペイロードが大きすぎます

​レート制限

​アップロード失敗

レート制限と同時実行数

レスポンス

トラブルシューティング

オブジェクト関連

ファイル関連

認証エラー

ストレージのクォータ超過

無効なコンテンツタイプ

ペイロードが大きすぎます

レート制限

アップロード失敗