API Referansı

Temel URL

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

Tüm endpoint'ler bu temel URL'ye görelidir. HTTPS gereklidir — HTTP istekleri yönlendirilir.

Kimlik Doğrulama

Okuma endpoint'leri (GET) açık ve ücretsizdir — kimlik doğrulaması gerekmez. Yazma endpoint'leri (POST, PATCH, DELETE), X-API-Key başlığı aracılığıyla iletilen bir API anahtarı gerektirir:

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.

Yanıt Formatı

Tüm yanıtlar application/json formatındadır. Tarihler ISO 8601 formatını kullanır. GIF kimlikleri 8 karakterli nanoid dizileridir (örn. xK9mQ2pL).

Tipik bir GIF nesnesi şu şekildedir:

{
  "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>"
  }
}

Sayfalandırma

Listeleme endpoint'leri sayfalandırılmış sonuçlar döndürür. page ve page_size sorgu parametrelerini kullanın:

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

Yanıt, sayfalandırma meta verilerini içerir:

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

Varsayılan sayfa boyutu 20'dir. Maksimum 100'dür.

Hız Sınırları

Hız sınırı başlıkları her yanıta dahil edilir: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIF'ler

GIF'leri Listele

GET /api/v1/gifs/

Oluşturulma tarihine göre sıralanmış (en yeniden eskiye) tüm herkese açık, silinmemiş GIF'leri döndürür.

Sorgu parametreleri: page, page_size, tag, shell, user.

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

GIF Detayı

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

Gömme kodları, indirme URL'leri ve dosya boyutları dahil tek bir GIF için tam meta veri.

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

Cast Verisi

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.

Döküm

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

Terminal oturumunun düz metin dökümü — ANSI kaçış kodları temizlenmiş komutlar ve çıktıları. Tam metin arama ve LLM bağlamı için kullanışlıdır.

Öne Çıkan GIF'ler

GET /api/v1/featured/

AgentGIF ekibi tarafından elle seçilmiş, yüksek kaliteli GIF'lerin özenle derlenmiş seçkisi.

Yükleme (Kimlik Doğrulaması Gerekli)

POST /api/v1/gifs/upload/

Meta verilerle bir GIF yükleyin. multipart/form-data kabul eder.

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 Güncelle (Kimlik Doğrulaması Gerekli)

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

Başlığı, açıklamayı, etiketleri veya görünürlüğü güncelleyin. Yalnızca GIF sahibi düzenleyebilir.

GIF Sil (Kimlik Doğrulaması Gerekli)

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

GIF'i geçici olarak siler. 30 gün içinde kurtarılabilir.

Arama

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

GIF başlıkları, açıklamaları, komutları, etiketleri ve dökümleri arasında tam metin arama. Minimum 2 karakter.

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

Etiketler

Etiketleri Listele

GET /api/v1/tags/

Popülerliğe göre sıralanmış GIF sayılarıyla birlikte tüm etiketler.

Etikete Göre GIF'ler

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

Belirli bir etikete sahip GIF'lerin sayfalandırılmış listesi.

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

Koleksiyonlar

Koleksiyonları Listele

GET /api/v1/collections/

Öne Çıkan Koleksiyonlar

GET /api/v1/collections/featured/

Koleksiyon Detayı

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

Koleksiyon meta verilerini ve sıralı GIF listesini döndürür.

Koleksiyon Oluştur (Kimlik Doğrulaması Gerekli)

POST /api/v1/collections/create/

Koleksiyon GIF'lerini Yönet (Kimlik Doğrulaması Gerekli)

Kullanıcılar

Kullanıcı Profili

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

Kullanıcının GIF'leri

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

Kimliği Doğrulanmış Kullanıcı

GET /api/v1/users/me/

API anahtarı ve yükleme istatistikleri dahil profilinizi döndürür. Kimlik doğrulaması gerektirir.

API Anahtarını Sıfırla

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

Yeni bir API anahtarı oluşturur. Eski anahtar anında geçersiz olur.

Temalar

Temaları Listele

GET /api/v1/themes/

Renk paletleriyle (ön plan, arka plan, ANSI renkleri) birlikte tüm 15 terminal teması.

Tema Detayı

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

Belirli bir tema için tam renk paleti. Cast dosyalarını doğru renklerle oluşturmak için kullanın.

Rozet Servisi

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

Sorgu parametreleriyle özelleştirin: ?theme=dracula, ?style=flat.

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

AI Tape Üreteci

Yapay zeka kullanarak doğal dil açıklamalarından VHS tape betikleri oluşturun.

Oluşturma İşi Başlat

POST /api/v1/gifs/generate/

Asenkron bir oluşturma işi başlatır. Durum sorgulamak için bir job_id döndürür.

Oluşturma Durumunu Kontrol Et

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

Oluşturma durumunu (pending, processing, completed, failed) ve tamamlandığında oluşturulan tape betiğini döndürür.

Hata Kodları

Hata yanıtları okunabilir bir mesaj içeren bir detail alanı içerir:

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

OpenAPI Spesifikasyonu

Tam OpenAPI 3.1 spesifikasyonu şu adreste mevcuttur:

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

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