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:])
コード例は分かりやすさのため、分割を1つずつ順番に送っています。大きなファイルを速く送るには、分割を並列に送ってください(4〜6本程度)。

認証とキー

すべてのリクエストに、キーを Authorization ヘッダーで付けます。

Authorization: Bearer gw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • キーは、発行した人の権限で動きます。APIで送ったファイルは、その人が送ったファイルとして扱われます。
  • 発行した人が組織を外れる、管理者でなくなる、停止される、法人プランの契約が切れる、API連携オプションを外す — のいずれかで、キーは使えなくなります。そのときは、ほかの管理者がキーを発行し直してください。
  • キーは組織で同時に10本まで有効にできます。システムごとにキーを分けると、1つを止めてもほかに影響しません。
  • キーには、使える接続元IPを登録できます(任意・50件まで。203.0.113.10 や 203.0.113.0/24 の形)。組織のログインIP制限を設定している場合は、両方を満たす必要があります。
  • キーは当社に保存されません(照合用のハッシュ値だけを持ちます)。失くしたときは停止して、新しく発行してください。
キーはサーバー側だけで使ってください。ブラウザのJavaScript・スマートフォンアプリ・公開リポジトリにキーを置くと、だれでも読み取れてしまいます。

アップロードの流れ

1ファイルを送る手順は次のとおりです。大きなファイルも途中から再開できるよう、25MiBずつに分けて送ります。

  1. 開始(POST /uploads)— 分割の数と、送り方(direct_upload)が返る
  2. 送り先URLの発行(POST /uploads/presign)→ 各URLへ分割を PUT し、ETag を控える
  3. 完了(POST /uploads/complete)— ファイルIDが返る
  4. ファイルの数だけ 1〜3 を繰り返す
  5. まとめの作成(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_typestring例: video/mp4。分からなければ application/octet-stream
retention_daysnumber保存日数。3・5・7・14・30・60・90・111 のどれか。省略すると7日。組織のポリシーの上限以内
passwordstringダウンロードのパスワード(任意)
download_limitnumberダウンロード回数の上限。0または省略で無制限(組織のポリシーで上限がある場合はその範囲で必須)
notify_on_downloadbooleanダウンロードされたら、キーを発行した人にメールで知らせる

応答

項目型説明
upload_idstringこのアップロードの識別子。以降のすべての呼び出しで使う
keystring保存先のキー。以降のすべての呼び出しで使う
chunk_sizenumber分割1つの大きさ(いまは 25MiB = 26214400 バイト)。この値で分けること
total_partsnumber分割の数
download_keystring完了のときにそのまま送り返す
direct_uploadbooleantrue なら保存先へ直接送る(送り先URLの発行)。false ならギガワタス経由で送る(中継で送る)

送り先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)はファイルの情報です。主な項目:

応答

項目型説明
idstringファイルID。まとめの作成・削除に使う
original_name / size / mime_typeファイル名・バイト数・種類
download_urlstringこのファイル単体の共有URL(https://giga-watasu.jp/d/…)
download_url_keystringURLの末尾のキー
expires_atstring期限(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。キーを発行した人のファイルに限る
passwordstringまとめのパスワード(任意)
download_limitnumberまとめのダウンロード回数の上限(任意)
notify_on_downloadbooleanダウンロードされたら、キーを発行した人にメールで知らせる

応答(201)

項目型説明
idstringまとめのID(削除に使う)
download_urlstring共有URL(https://giga-watasu.jp/b/…)。これをメールなどで渡す
download_url_keystringURLの末尾のキー
file_count / total_sizenumberファイル数・合計バイト数
expires_atstring期限。中のファイルのうち、いちばん早く切れるものに合わせる

公開情報の確認

GET/api/v1/files/{download_url_key} ・ /api/v1/bundles/{download_url_key}

受け取る方に見えている情報(名前・大きさ・期限など)を返します。期限切れや削除済みなら 404 または 410 です。

削除

DELETE/api/v1/files/{id} ・ /api/v1/bundles/{id}

ファイルまたはまとめを削除します。消せるのは、キーを発行した人のもの(その人が画面から送った分を含む)だけです。同じ組織の別の人のものは消せません。

まとめを削除しても、中のファイルは残ります(ファイル単体のURLは使えるまま)。ファイルを削除すると、そのファイルはまとめからも外れます。

エラー

エラーは次の形で返します。error は人が読む日本語、code はプログラムで判定するための英字です(code は認証まわりのエラーにだけ付きます)。

{ "error": "APIキーが正しくありません", "code": "invalid_api_key" }
HTTPcode意味
401missing_api_keyAuthorization ヘッダーが無い、またはAPIキーの形でない(ログイン用のトークンは使えない)
401invalid_api_key存在しないキー
401api_key_revoked停止されたキー
401api_key_owner_inactiveキーを発行した人が組織にいない・管理者でない・停止中
403account_bannedキーを発行した人が利用停止中
403org_inactive法人プランの契約が有効でない
403api_not_enabledAPI連携オプションが有効でない
403ip_not_allowed接続元IPが許可されていない
429rate_limited呼び出しが多すぎる。Retry-After ヘッダーの秒数だけ待って再試行
503temporarily_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)
ポリシーの「受取人の本人確認」を有効にしていると、受け取る方はギガワタスから届いた確認メールを通さないと受け取れません。APIで発行したURLを自社のメールで渡す使い方では受け取れなくなるため、APIを使う組織ではこの設定を外してください。

途中で切れたとき

  • 分割のPUTが失敗したら、その分割だけ送り直してください(送り先URLの期限が切れていたら、発行し直す)。
  • プログラムが止まったときは、送り終えた分割の確認で届いている分割を調べ、残りだけ送ってから完了します。
  • あきらめるときは 中止 を呼んでください。

料金の数え方

月額5,500円(税込)に、API経由で預かっている保存容量 1TB が含まれます。

  • 数えるのは、APIで送り、いま保存されているファイルの合計です(GET /me の usage.bytes)。画面から送ったファイルは数えません。
  • 期限が切れたファイル・削除したファイルは、その時点で数えなくなります。
  • 1TBを超えた月は、超えた分について1TBごとに2,200円(税込)をいただきます。1TBは1012バイトです。
  • 呼び出し回数・ダウンロード量では課金しません。

くわしくは API連携オプション利用規定 をご覧ください。

安全に使うために

  • キーは環境変数や秘密情報の保管庫に入れ、ソースコードに直接書かないでください。
  • サーバーの接続元IPが決まっているなら、キーにIP制限を付けてください。
  • システムごと・用途ごとにキーを分け、使わなくなったキーは停止してください。
  • 担当者の異動・退職のときは、その人が発行したキーを確認してください(組織を外れると自動で使えなくなります)。
  • 受け取る方に渡す共有URLは、必要ならパスワードやダウンロード回数で守ってください。

変更履歴

  • 2026年11月20日 — v1 を公開

ご不明な点は お問い合わせ ください。組み込みの相談・技術サポート・組み込み代行も承ります(導入支援)。

プライバシーマーク

株式会社グッドヒルシステムズ(ギガワタス)は、プライバシーマークを取得しています。また、当サイトはSSLを導入しており、お客様の個人情報などの大切なデータを安全にやりとりできます。

取得状況はこちら →