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

임베드 코드, 다운로드 URL, 파일 크기를 포함한 단일 GIF의 전체 메타데이터.

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/

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/

색상 팔레트(전경, 배경, ANSI 색상)를 포함한 모든 15개 터미널 테마.

테마 상세

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

특정 테마의 전체 색상 팔레트. cast 파일을 올바른 색상으로 렌더링할 때 사용하세요.

Badge 서비스

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 생성기

AI를 사용하여 자연어 설명으로 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 스펙

전체 OpenAPI 3.1 스펙은 다음에서 확인할 수 있습니다:

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

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