Справочник API

Базовый URL

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

Все эндпоинты относительны этого базового URL. Требуется HTTPS — HTTP-запросы перенаправляются.

Аутентификация

Эндпоинты чтения (GET) являются открытыми и бесплатными — аутентификация не требуется. Эндпоинты записи (POST, PATCH, DELETE) требуют API-ключ, передаваемый через заголовок X-API-Key:

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. ID GIF — это 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'

Данные cast

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/

Кураторская подборка высококачественных GIF, выбранных командой AgentGIF вручную.

Загрузка (требуется аутентификация)

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

Полная цветовая палитра для конкретной темы. Используйте это для рендеринга cast-файлов с правильными цветами.

Сервис бейджей

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 Tape

Генерация сценариев VHS tape из описаний на естественном языке с помощью ИИ.

Создать задачу генерации

POST /api/v1/gifs/generate/

Запускает асинхронную задачу генерации. Возвращает job_id для опроса статуса.

Проверить статус генерации

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

Возвращает статус генерации (pending, processing, completed, failed) и сгенерированный сценарий tape при завершении.

Коды ошибок

Ответы с ошибками включают поле detail с понятным человеку сообщением:

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

OpenAPI Spec

Полная спецификация OpenAPI 3.1 доступна по адресу:

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

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