API リファレンス

ベース URL

https://agentgif.com/api/v1/

すべてのエンドポイントはこのベース URL からの相対パスです。HTTPS が必要 — HTTP リクエストはリダイレクトされます。

認証

読み取りエンドポイント (GET) は オープンで無料 — 認証不要。書き込みエンドポイント (POST、PATCH、DELETE) には X-API-Key ヘッダーで渡す API キーが必要です:

curl -H "X-API-Key: YOUR_API_KEY" https://agentgif.com/api/v1/gifs/upload/ \
  -F "[email protected]" -F "title=Demo"

Get your API key at Settings → API Key. You can reset it at any time via the settings page or the /api/v1/users/me/api-key/reset/ endpoint.

レスポンス形式

すべてのレスポンスは application/json 形式です。日付は ISO 8601 形式を使用します。GIF ID は 8 文字の nanoid 文字列です (例: xK9mQ2pL)。

典型的な GIF オブジェクトは次のようになります:

{
  "id": "xK9mQ2pL",
  "title": "Git Interactive Rebase",
  "slug": "git-rebase",
  "command": "git rebase -i HEAD~3",
  "shell": "zsh",
  "description": "Interactive rebase to squash commits",
  "gif_url": "https://media.agentgif.com/xK9mQ2pL.gif",
  "mp4_url": "https://media.agentgif.com/xK9mQ2pL.mp4",
  "cast_url": "https://media.agentgif.com/xK9mQ2pL.cast",
  "thumbnail_url": "https://media.agentgif.com/xK9mQ2pL_thumb.png",
  "width": 1000,
  "height": 580,
  "frames": 142,
  "duration_ms": 8500,
  "file_size_bytes": 245760,
  "visibility": "public",
  "view_count": 1234,
  "tags": ["git", "rebase", "version-control"],
  "user": {"username": "agentgif"},
  "tool": {"name": "git", "slug": "git"},
  "theme": {"name": "Catppuccin Mocha", "slug": "catppuccin-mocha"},
  "created_at": "2026-03-15T10:30:00Z",
  "detail_url": "https://agentgif.com/@agentgif/git-rebase/",
  "embed_codes": {
    "markdown": "[![Git Rebase](https://media.agentgif.com/xK9mQ2pL.gif)](https://agentgif.com/xK9mQ2pL)",
    "html": "<a href=\"https://agentgif.com/xK9mQ2pL\"><img src=\"...\" /></a>"
  }
}

ページネーション

リストエンドポイントはページネーションされた結果を返します。page と page_size クエリパラメーターを使用してください:

GET /api/v1/gifs/?page=2&page_size=20

レスポンスにはページネーションメタデータが含まれます:

{
  "count": 886,
  "next": "https://agentgif.com/api/v1/gifs/?page=3",
  "previous": "https://agentgif.com/api/v1/gifs/?page=1",
  "results": [...]
}

デフォルトのページサイズは 20 です。最大は 100 です。

レート制限

レート制限ヘッダーはすべてのレスポンスに含まれます: X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。

GIF

GIF 一覧

GET /api/v1/gifs/

削除されていないすべての公開 GIF を作成日順 (新しい順) で返します。

クエリパラメーター: page, page_size, tag, shell, user.

curl -s https://agentgif.com/api/v1/gifs/?tag=docker&page_size=5 | jq '.count'

GIF 詳細

GET /api/v1/gifs/{id}/

単一 GIF の完全なメタデータ (埋め込みコード、ダウンロード URL、ファイルサイズを含む)。

curl -s https://agentgif.com/api/v1/gifs/xK9mQ2pL/ | jq '.title, .gif_url'

キャストデータ

GET /api/v1/gifs/{id}/cast/

Returns the raw asciinema v2 cast file — a JSON header line followed by newline-delimited event tuples [timestamp, event_type, data]. This is the machine-readable layer that AI agents use to understand the terminal session.

トランスクリプト

GET /api/v1/gifs/{id}/transcript/

ターミナルセッションのプレーンテキストトランスクリプト — ANSI エスケープコードを除去したコマンドとその出力。全文検索と LLM コンテキストに役立ちます。

おすすめ GIF

GET /api/v1/featured/

AgentGIF チームが手動で厳選した高品質 GIF のコレクション。

アップロード (認証必要)

POST /api/v1/gifs/upload/

メタデータ付きで GIF をアップロードします。multipart/form-data を受け付けます。

curl -X POST https://agentgif.com/api/v1/gifs/upload/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Docker Compose Up" \
  -F "command=docker compose up -d" \
  -F "tags=docker,compose,containers" \
  -F "[email protected]"

GIF 更新 (認証必要)

PATCH /api/v1/gifs/{id}/edit/

タイトル、説明、タグ、公開設定を更新します。GIF のオーナーのみ編集可能。

GIF 削除 (認証必要)

DELETE /api/v1/gifs/{id}/delete/

GIF をソフト削除します。30 日以内に復元できます。

検索

GET /api/v1/search/?q={query}

GIF タイトル、説明、コマンド、タグ、トランスクリプトにわたる全文検索。最低 2 文字。

curl -s "https://agentgif.com/api/v1/search/?q=git+rebase&sort=views" | jq '.results[0].title'

タグ

タグ一覧

GET /api/v1/tags/

GIF 数付きのすべてのタグ (人気順)。

タグ別 GIF

GET /api/v1/tags/{slug}/gifs/

特定のタグを持つ GIF のページネーション付きリスト。

curl -s https://agentgif.com/api/v1/tags/docker/gifs/ | jq '.count'

コレクション

コレクション一覧

GET /api/v1/collections/

おすすめコレクション

GET /api/v1/collections/featured/

コレクション詳細

GET /api/v1/collections/{slug}/

コレクションのメタデータと GIF の順序付きリストを返します。

コレクション作成 (認証必要)

POST /api/v1/collections/create/

コレクション GIF 管理 (認証必要)

ユーザー

ユーザープロフィール

GET /api/v1/users/{username}/

ユーザーの GIF

GET /api/v1/users/{username}/gifs/

認証済みユーザー

GET /api/v1/users/me/

API キーとアップロード統計を含むプロフィールを返します。認証が必要です。

API キーをリセット

POST /api/v1/users/me/api-key/reset/

新しい API キーを生成します。古いキーは即座に無効化されます。

テーマ

テーマ一覧

GET /api/v1/themes/

15 のターミナルテーマとそのカラーパレット (前景色、背景色、ANSI カラー)。

テーマ詳細

GET /api/v1/themes/{slug}/

特定のテーマの完全なカラーパレット。キャストファイルを正しい色でレンダリングするために使用します。

バッジサービス

Terminal-themed package badges — a developer-friendly alternative to shields.io. See the Badge Playground for a visual builder.

クエリパラメーターでカスタマイズ: ?theme=dracula、?style=flat。

<img src="https://agentgif.com/badge/pypi/requests/version.svg?theme=catppuccin-mocha" />

AI テープジェネレーター

AI を使用して自然言語の説明から VHS テープスクリプトを生成します。

生成ジョブを作成

POST /api/v1/gifs/generate/

非同期生成ジョブを開始します。ステータスをポーリングするための job_id を返します。

生成ステータスを確認

GET /api/v1/gifs/generate/{job_id}/

生成ステータス (pending、processing、completed、failed) と完了時の生成されたテープスクリプトを返します。

エラーコード

エラーレスポンスには人間が読めるメッセージを含む detail フィールドが含まれます:

{
  "detail": "Authentication credentials were not provided."
}

OpenAPI 仕様

完全な OpenAPI 3.1 仕様は以下で利用可能です:

https://agentgif.com/api/openapi.json

Import it into Swagger UI, Insomnia, or any OpenAPI-compatible tool.