Blob アップロードトークン

POST

upload-tokens

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

string

必須

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

アップロードトークンを使うと、サーバーが短期間有効なトークンを発行し、ブラウザやモバイルアプリがそれを使って Blob Storage に直接アップロードできます。ファイルがサーバーを経由することはなく、API キーがサーバーの外に出ることもありません。blob:write スコープと有料プランが必要です。トークンはオブジェクトのアップロードまたはチャンクアップロードのルートの Authorization ヘッダーで送信し、それ以外では機能しません (403 UPLOAD_TOKEN_NOT_ALLOWED)。発行時に設定したものはすべて固定されます: ブラウザは名前、プレフィックス、公開範囲、有効期限、メタデータを変更したり、より大きなファイルを送信したり、別のファイル形式を使用したりすることはできません。

アップロードごとに 1 回分を消費します: オブジェクトのアップロードの呼び出し 1 回、またはチャンクアップロードの開始 1 回です (そのパートの送信と完了で追加の消費はありません)。
name を指定しない場合はブラウザが名前を選び、その名前には常にセキュリティハッシュが付与されるため、トークンが漏えいしても既存のファイルが置き換えられることはありません。
トークンは、使用回数を使い切ったとき (401 UPLOAD_TOKEN_USED)、有効期限が切れたとき、または発行元の API キーが取り消されたとき (401 ACCESS_DENIED) に機能しなくなります。

string

ファイル名を固定します。指定しない場合、ブラウザがクエリで name を送信します。

string

プレフィックスを固定します。異なるプレフィックスを送信したブラウザは 403 PREFIX_NOT_ALLOWED を受け取ります。

boolean

公開範囲を固定します。

boolean

name を指定した場合のみ: false にすると、アップロードでその名前のファイルを置き換えられます。それ以外の場合、名前には常にハッシュが付与されます。

string | null

有効期限を固定します (30d、6h)。有効期限なしの場合は null。7 日未満には Enterprise が必要です。

number

最大ファイルサイズ (バイト)。512〜10737418240 (10 GiB) です。

string[]

受け付ける拡張子。1〜20 個、小文字でドットなし (png、tar.gz) です。

object

トークンでアップロードされるすべてのファイルに追加されるメタデータ。Pro と Enterprise のみ。

number

デフォルト:"900"

トークンの有効期間。60〜3600 秒です。

number

デフォルト:"1"

トークンで許可されるアップロード回数。1〜100 です。

レート制限

1 分間に 120 トークン (RATE_LIMITED、429)。発行時には何も保存されないため、エンドユーザーのアップロードごとに 1 つのトークンを発行しても問題ありません。

レスポンス

string

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

object

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

string

アップロードトークン (squp_...)。これをブラウザに渡します。

ISO 8601

トークンの有効期限。

number

トークンで許可されるアップロード回数。

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

エラー

コード	HTTP	発生する状況
`INVALID_BODY`	400	本文が JSON オブジェクトではない。
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` / `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_SECURITY_HASH` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_METADATA`	400	固定する値が無効。
`INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` / `INVALID_EXPIRES_IN` / `INVALID_MAX_USES`	400	制限値が範囲外。
`UPLOAD_TOKEN_TOO_LARGE`	400	1 つのトークンに対してオプションが多すぎる。メタデータまたは拡張子リストを短くしてください。
`PERMISSION_DENIED`	401	アカウントに有効な有料プランがない。
`UPGRADE_REQUIRED`	403	有効期限またはメタデータに上位のプランが必要。
`RATE_LIMITED`	429	1 分間に 120 トークンを超えた。

ブラウザがアップロードする際のエラー: 401 UPLOAD_TOKEN_USED (使い切った)、401 ACCESS_DENIED (期限切れまたは取り消し済み)、403 PREFIX_NOT_ALLOWED (別のプレフィックス)、400 FILE_TYPE_NOT_ALLOWED (許可されていない拡張子)、413 FILE_TOO_LARGE (max_size 超過)。

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

はじめに

オブジェクト

チャンクアップロード

アカウント

共有リンク

S3

Blob アップロードトークン

レート制限

レスポンス

エラー

​レート制限

​レスポンス

​エラー

レート制限

レスポンス

エラー