API Reference v1
ギガワタス API 仕様書
2026年11月20日 版
はじめに
ギガワタスAPIは、貴社のシステムからファイルをアップロードし、共有URLを発行するためのAPIです。HTTPSでJSONをやりとりします。
入口: https://giga-watasu.jp/api/v1- 使えるのは、法人プランにAPI連携オプションを付けた組織です(無料トライアル中も使えます)。
- キーは、法人コンソールの「API連携」で、組織のオーナーまたは管理者が発行します。
- 受け取る方は、画面から送ったときと同じ共有ページから受け取ります(会員登録は不要です)。
- 文字コードはUTF-8です。日時はすべてUTC(ISO 8601)で返します。
クイックスタート
1. キーを発行する — 法人コンソール →「API連携」→「キーを発行」。表示されたキー(gw_live_ で始まる文字列)は、その場でしか見られません。環境変数などに保存してください。
2. つながるか確かめる
curl https://giga-watasu.jp/api/v1/me -H "Authorization: Bearer $GIGAWATASU_API_KEY"組織名が返ってくれば準備完了です。
3. ファイルを送って共有URLを受け取る — 次のコード例は、指定したファイルを送り、1本の共有URLにまとめて表示します。どれも本番環境で動作を確かめています。
"""ギガワタス API: ファイルをアップロードして、共有URL(まとめ)を1本発行する。
使い方:
pip install requests
export GIGAWATASU_API_KEY="gw_live_..."
python upload.py 納品データ.mp4 解説.pdf
最後に共有URL(https://giga-watasu.jp/b/...)を表示します。
"""
import os
import sys
import time
import requests
BASE_URL = "https://giga-watasu.jp/api/v1"
API_KEY = os.environ["GIGAWATASU_API_KEY"]
RETENTION_DAYS = 30 # 3, 5, 7, 14, 30, 60, 90, 111 のどれか(組織の上限以内)
PRESIGN_BATCH = 20 # 送り先URLは有効期限があるので、少しずつ取る
session = requests.Session()
session.headers["Authorization"] = f"Bearer {API_KEY}"
def api(method, path, **kwargs):
"""APIを呼ぶ。429(呼び出しが多すぎる)は Retry-After 秒だけ待って再試行する。"""
for _ in range(5):
res = session.request(method, BASE_URL + path, timeout=60, **kwargs)
if res.status_code == 429:
time.sleep(int(res.headers.get("Retry-After", "5")))
continue
if res.status_code >= 400:
raise RuntimeError(f"{method} {path} -> {res.status_code} {res.text}")
return res.json() if res.content else None
raise RuntimeError(f"{method} {path} -> 429 が続きました")
def read_part(f, chunk_size, part_number):
f.seek((part_number - 1) * chunk_size)
return f.read(chunk_size)
def upload_file(path):
"""1ファイルを送り、ファイルの情報(id など)を返す。"""
name = os.path.basename(path)
size = os.path.getsize(path)
mime = "application/octet-stream"
init = api("POST", "/uploads", json={
"file_name": name, "file_size": size, "mime_type": mime,
"retention_days": RETENTION_DAYS,
})
upload_id, key = init["upload_id"], init["key"]
chunk_size, total = init["chunk_size"], init["total_parts"]
parts = []
try:
with open(path, "rb") as f:
if init["direct_upload"]:
# 保存先へ直接送る(通常はこちら)
for start in range(1, total + 1, PRESIGN_BATCH):
numbers = list(range(start, min(start + PRESIGN_BATCH, total + 1)))
urls = api("POST", "/uploads/presign", json={
"upload_id": upload_id, "key": key, "part_numbers": numbers,
})["urls"]
for u in urls:
body = read_part(f, chunk_size, u["part_number"])
res = requests.put(u["url"], data=body, timeout=600)
res.raise_for_status()
parts.append({"part_number": u["part_number"],
"etag": res.headers["ETag"].strip('"')})
else:
# ギガワタスのサーバー経由で送る
for n in range(1, total + 1):
res = api("PUT", "/uploads/part", data=read_part(f, chunk_size, n), headers={
"X-Upload-ID": upload_id, "X-Upload-Key": key, "X-Part-Number": str(n),
"Content-Type": "application/octet-stream",
})
parts.append({"part_number": n, "etag": res["etag"]})
return api("POST", "/uploads/complete", json={
"upload_id": upload_id, "key": key, "parts": parts,
"file_name": name, "file_size": size, "mime_type": mime,
"download_key": init["download_key"], "retention_days": RETENTION_DAYS,
})
except Exception:
api("POST", "/uploads/abort", json={"upload_id": upload_id, "key": key})
raise
def main(paths):
file_ids = []
for path in paths:
info = upload_file(path)
print(f"送信済み: {info['original_name']}")
file_ids.append(info["id"])
bundle = api("POST", "/bundles", json={"name": "納品データ", "file_ids": file_ids})
print("共有URL:", bundle["download_url"])
print("期限:", bundle["expires_at"])
if __name__ == "__main__":
if len(sys.argv) < 2:
sys.exit("使い方: python upload.py ファイル [ファイル ...]")
main(sys.argv[1:])
認証とキー
すべてのリクエストに、キーを Authorization ヘッダーで付けます。
Authorization: Bearer gw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- キーは、発行した人の権限で動きます。APIで送ったファイルは、その人が送ったファイルとして扱われます。
- 発行した人が組織を外れる、管理者でなくなる、停止される、法人プランの契約が切れる、API連携オプションを外す — のいずれかで、キーは使えなくなります。そのときは、ほかの管理者がキーを発行し直してください。
- キーは組織で同時に10本まで有効にできます。システムごとにキーを分けると、1つを止めてもほかに影響しません。
- キーには、使える接続元IPを登録できます(任意・50件まで。
203.0.113.10や203.0.113.0/24の形)。組織のログインIP制限を設定している場合は、両方を満たす必要があります。 - キーは当社に保存されません(照合用のハッシュ値だけを持ちます)。失くしたときは停止して、新しく発行してください。
アップロードの流れ
1ファイルを送る手順は次のとおりです。大きなファイルも途中から再開できるよう、25MiBずつに分けて送ります。
- 開始(
POST /uploads)— 分割の数と、送り方(direct_upload)が返る - 送り先URLの発行(
POST /uploads/presign)→ 各URLへ分割をPUTし、ETagを控える - 完了(
POST /uploads/complete)— ファイルIDが返る - ファイルの数だけ 1〜3 を繰り返す
- まとめの作成(
POST /bundles)— 共有URLが返る
通常は direct_upload: true で、データはギガワタスのサーバーを通らず、保存先へ直接送られます。false が返ったときは、2 の代わりに 中継で送る(PUT /uploads/part)を使ってください。コード例は両方に対応しています。
エンドポイント
パスはすべて https://giga-watasu.jp/api/v1 からの相対です(下の表記は /api/v1 から書いています)。
接続確認
GET/api/v1/me
キーが使えるかを確かめます。組織名と、API経由で預かっている保存容量を返します。
{
"organization": { "id": "…", "name": "株式会社サンプル" },
"api_key_id": "…",
"usage": { "files": 12, "bytes": 3400000000 },
"included_bytes": 1000000000000
}アップロードの開始
POST/api/v1/uploads
ファイル1つごとに呼びます。組織のポリシーに合わない指定(保存期間の上限を超える、パスワード必須なのに無い など)は、ここで 403 になります。
リクエスト(JSON)
| 項目 | 型 | 説明 |
|---|---|---|
| file_name必須 | string | 受け取る方に見えるファイル名 |
| file_size必須 | number | バイト数(最大333GB) |
| mime_type | string | 例: video/mp4。分からなければ application/octet-stream |
| retention_days | number | 保存日数。3・5・7・14・30・60・90・111 のどれか。省略すると7日。組織のポリシーの上限以内 |
| password | string | ダウンロードのパスワード(任意) |
| download_limit | number | ダウンロード回数の上限。0または省略で無制限(組織のポリシーで上限がある場合はその範囲で必須) |
| notify_on_download | boolean | ダウンロードされたら、キーを発行した人にメールで知らせる |
送り先URLの発行(直送)
POST/api/v1/uploads/presign
分割ごとの送り先URLを発行します。1回で最大100個まで。URLの有効期限は60分なので、大きなファイルは20個ずつ程度に分けて、送る直前に取ってください。
// リクエスト
{ "upload_id": "…", "key": "…", "part_numbers": [1, 2, 3] }
// 応答
{ "urls": [ { "part_number": 1, "url": "https://s3.ap-northeast-1.wasabisys.com/…" }, … ] }受け取った url へ、ファイルの該当部分を本文にして PUT します。分割 n の範囲は、先頭から (n-1) × chunk_size バイト目から chunk_size バイト(最後の分割は残り全部)です。 このPUTにはAPIキーを付けません(URL自体に期限つきの許可が入っています)。応答ヘッダーの ETag の値(前後の " を外したもの)を、分割番号と組にして控えてください。
中継で送る(direct_upload が false のとき)
PUT/api/v1/uploads/part
分割1つを本文にして送ります。次のヘッダーを付けます。
ヘッダー
| 項目 | 型 | 説明 |
|---|---|---|
| X-Upload-ID必須 | string | 開始で受け取った upload_id |
| X-Upload-Key必須 | string | 開始で受け取った key |
| X-Part-Number必須 | number | 分割番号(1から) |
// 応答
{ "etag": "…", "part_number": 1 }送り終えた分割の確認
POST/api/v1/uploads/list-parts
途中で切れたときに、どの分割が届いているかを確かめます。届いていない分割だけ送り直してから、完了してください。
// リクエスト
{ "upload_id": "…", "key": "…" }
// 応答
{ "parts": [ { "part_number": 1, "etag": "\"…\"", "size": 26214400 }, … ] }アップロードの完了
POST/api/v1/uploads/complete
すべての分割を送り終えたら呼びます。ここで初めてファイルとして登録され、受け取れる状態になります。パスワード・ダウンロード回数・通知の設定は、この呼び出しで送った値が使われます(開始と同じ値を送ってください)。
リクエスト(JSON)
| 項目 | 型 | 説明 |
|---|---|---|
| upload_id / key必須 | string | 開始で受け取った値 |
| parts必須 | array | [{"part_number": 1, "etag": "…"}, …] すべての分割 |
| file_name / file_size / mime_type必須 | 開始と同じ値 | |
| download_key必須 | string | 開始で受け取った値 |
| retention_days / password / download_limit / notify_on_download | 開始と同じ値 |
応答(201)はファイルの情報です。主な項目:
応答
| 項目 | 型 | 説明 |
|---|---|---|
| id | string | ファイルID。まとめの作成・削除に使う |
| original_name / size / mime_type | ファイル名・バイト数・種類 | |
| download_url | string | このファイル単体の共有URL(https://giga-watasu.jp/d/…) |
| download_url_key | string | URLの末尾のキー |
| expires_at | string | 期限(UTC・ISO 8601) |
| has_password / download_limit / download_count | パスワードの有無・回数の上限・ダウンロードされた回数 |
アップロードの中止
POST/api/v1/uploads/abort
送るのをやめるときに呼びます。送り途中の分割は破棄されます。{ "upload_id": "…", "key": "…" }
共有URL(まとめ)の作成
POST/api/v1/bundles
完了したファイルを1つ以上まとめて、1本の共有URLを作ります(最大500件)。受け取る方は、このURLから一覧を見て、1つずつまたはまとめてダウンロードできます。1ファイルだけのときも、まとめを作ってそのURLを渡すと、受け取る方の画面がいつも同じになります。
リクエスト(JSON)
| 項目 | 型 | 説明 |
|---|---|---|
| name必須 | string | 受け取る方に見える名前(例: 山田様 納品データ) |
| file_ids必須 | string[] | 完了で受け取ったファイルID。キーを発行した人のファイルに限る |
| password | string | まとめのパスワード(任意) |
| download_limit | number | まとめのダウンロード回数の上限(任意) |
| notify_on_download | boolean | ダウンロードされたら、キーを発行した人にメールで知らせる |
応答(201)
| 項目 | 型 | 説明 |
|---|---|---|
| id | string | まとめのID(削除に使う) |
| download_url | string | 共有URL(https://giga-watasu.jp/b/…)。これをメールなどで渡す |
| download_url_key | string | URLの末尾のキー |
| file_count / total_size | number | ファイル数・合計バイト数 |
| expires_at | string | 期限。中のファイルのうち、いちばん早く切れるものに合わせる |
公開情報の確認
GET/api/v1/files/{download_url_key} ・ /api/v1/bundles/{download_url_key}
受け取る方に見えている情報(名前・大きさ・期限など)を返します。期限切れや削除済みなら 404 または 410 です。
削除
DELETE/api/v1/files/{id} ・ /api/v1/bundles/{id}
ファイルまたはまとめを削除します。消せるのは、キーを発行した人のもの(その人が画面から送った分を含む)だけです。同じ組織の別の人のものは消せません。
エラー
エラーは次の形で返します。error は人が読む日本語、code はプログラムで判定するための英字です(code は認証まわりのエラーにだけ付きます)。
{ "error": "APIキーが正しくありません", "code": "invalid_api_key" }| HTTP | code | 意味 |
|---|---|---|
| 401 | missing_api_key | Authorization ヘッダーが無い、またはAPIキーの形でない(ログイン用のトークンは使えない) |
| 401 | invalid_api_key | 存在しないキー |
| 401 | api_key_revoked | 停止されたキー |
| 401 | api_key_owner_inactive | キーを発行した人が組織にいない・管理者でない・停止中 |
| 403 | account_banned | キーを発行した人が利用停止中 |
| 403 | org_inactive | 法人プランの契約が有効でない |
| 403 | api_not_enabled | API連携オプションが有効でない |
| 403 | ip_not_allowed | 接続元IPが許可されていない |
| 429 | rate_limited | 呼び出しが多すぎる。Retry-After ヘッダーの秒数だけ待って再試行 |
| 503 | temporarily_unavailable | 一時的に認証できない。少し待って再試行してよい |
そのほか、指定の誤り(保存日数が選べない値・ファイルが大きすぎる など)は 400、組織のポリシー違反は 403 を、error だけ付けて返します。5xx が返ったときは、時間をおいて再試行してください。
上限
- 呼び出し: キー1本あたり 毎分1,200回
- ファイル数: キーを発行した人あたり 毎分600件(開始の回数)
- 認証の失敗: 同じ接続元から毎分30回を超えると、しばらくすべて 429
- 1ファイル: 最大333GB / 分割: 25MiB / 送り先URL: 1回100個まで・有効期限60分
- まとめ: 1つに最大500ファイル
上限を超えると 429 を返し、Retry-After ヘッダーに待つ秒数を入れます。
組織のポリシーとの関係
法人コンソールで設定したポリシーは、APIから送ったファイルにも同じようにかかります。
- 保存期間の上限 — 超える
retention_daysは 403 - パスワード必須 —
passwordが無いと 403 - ダウンロード回数の上限 —
download_limitを上限以内で指定しないと 403 - ログインIP制限 — 接続元IPがこの範囲に無いと 403(
ip_not_allowed)
途中で切れたとき
- 分割のPUTが失敗したら、その分割だけ送り直してください(送り先URLの期限が切れていたら、発行し直す)。
- プログラムが止まったときは、送り終えた分割の確認で届いている分割を調べ、残りだけ送ってから完了します。
- あきらめるときは 中止 を呼んでください。
料金の数え方
月額5,500円(税込)に、API経由で預かっている保存容量 1TB が含まれます。
- 数えるのは、APIで送り、いま保存されているファイルの合計です(
GET /meのusage.bytes)。画面から送ったファイルは数えません。 - 期限が切れたファイル・削除したファイルは、その時点で数えなくなります。
- 1TBを超えた月は、超えた分について1TBごとに2,200円(税込)をいただきます。1TBは1012バイトです。
- 呼び出し回数・ダウンロード量では課金しません。
くわしくは API連携オプション利用規定 をご覧ください。
安全に使うために
- キーは環境変数や秘密情報の保管庫に入れ、ソースコードに直接書かないでください。
- サーバーの接続元IPが決まっているなら、キーにIP制限を付けてください。
- システムごと・用途ごとにキーを分け、使わなくなったキーは停止してください。
- 担当者の異動・退職のときは、その人が発行したキーを確認してください(組織を外れると自動で使えなくなります)。
- 受け取る方に渡す共有URLは、必要ならパスワードやダウンロード回数で守ってください。

