Dokumentasi API

Mendapatkan API Key

Masuk, buka Akun saya, lalu buka tab API. Key Anda ditampilkan di sana, beserta tombol Regenerate. Membuat ulang key akan langsung membatalkan key lama, jadi perbarui semua tempat yang memakainya sebelum Anda menekan tombolnya.

Tab itu juga memiliki key khusus unggah yang kedua dan independen - lihat tips di bawah dan Plugin Forum untuk kapan sebaiknya memakainya.

Autentikasi

Kirim key Anda sebagai header - cara yang disarankan, karena query string cenderung berakhir di log akses, log proxy, dan header Referer:

X-API-Key: YOUR_API_KEY

Parameter query ?key= juga berfungsi, dipertahankan demi kompatibilitas dengan integrasi lama dan perintah curl sekali pakai yang cepat. Jika keduanya ada, header yang dipakai.

?key=YOUR_API_KEY

Endpoint

Unggah, daftar, dan hapus memakai autentikasi dan pembatasan laju yang sama; file besar dapat dikirim per bagian terlebih dahulu.

POST /api - Unggah File

Mengunggah satu file untuk akun yang terautentikasi.

Jenis yang diterima: gambar JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC atau HEIF; video MP4, WEBM atau AVI (daftar pastinya dapat bertambah seiring waktu). HEIC/HEIF dan TIFF disimpan sebagai WebP, video selain MP4/WebM dikonversi ke MP4, dan gambar JPEG/PNG yang lebih besar dikonversi ke WebP tak lama setelah diunggah jika itu membuatnya jauh lebih kecil. Ukuran maksimal: 200MB; file yang terlalu besar atau tidak terbaca akan ditolak dengan 422.

Respons - 200 OK:

{
  "type": "success",
  "msg": "success",
  "data": {
    "id": "aB3xY9qRz1",
    "type": "image",
    "path": "https://i.yourimageshare.com/aB3xY9qRz1.png",
    "src": "https://yourimageshare.com/ib/aB3xY9qRz1.png",
    "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
    "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
    "width": 1920,
    "height": 1080,
    "size": 482113,
    "locked": false,
    "visibility": "unlisted",
    "title": null,
    "description": null,
    "expires_at": null,
    "duplicate": false,
    "delete_url": "https://yourimageshare.com/delete#iV3x...k9"
  }
}

POST /api/chunk - File Besar

Satu permintaan maksimal membawa 100MB. Untuk file yang lebih besar (hingga 200MB), atau agar setiap permintaan tetap kecil pada koneksi lambat, kirim file per bagian maksimal 5MB, lalu akhiri dengan POST /api:

1. Pilih upload id: 32 karakter heksadesimal acak.
2. Untuk setiap bagian, POST /api/chunk (multipart/form-data) dengan upload_id, index (mulai dari 0), total (jumlah bagian), dan byte-nya di chunk. Jawabannya adalah {"type": "success", "chunk_size": 5242880}.
3. POST /api dengan upload_id dan filename sebagai pengganti uploads, ditambah field unggah lainnya. Jawabannya adalah respons unggah yang normal.

Bagian dari unggahan yang tidak diselesaikan akan dihapus setelah 2 jam. Hanya POST /api penutup yang dihitung dalam batas laju unggah.

GET /api/{id} dan PATCH /api/{id} - Satu Unggahan

GET mengembalikan salah satu unggahan Anda dengan field yang sama seperti daftar di bawah. PATCH mengubah visibility, title, atau description (field form atau JSON; judul atau deskripsi kosong akan menghapusnya) dan menjawab dengan unggahan yang telah diperbarui. Keduanya memerlukan API key lengkap; 404 jika unggahan tersebut tidak ada di akun Anda.

curl -X PATCH https://yourimageshare.com/api/aB3xY9qRz1 \
  -H "X-API-Key: YOUR_API_KEY" -d visibility=public -d title="Sunset"

POST /api/{id}/replace - Ganti File

Menukar file di balik salah satu unggahan Anda dan mempertahankan id, halaman, dan semua link-nya. Jenis apa pun yang diizinkan dapat dipakai, bahkan yang berbeda (gambar bisa menjadi video). Kirim file baru sebagai uploads (atau upload_id dari file yang dikirim per bagian dengan POST /api/chunk); keep_original berfungsi seperti pada unggahan. File baru mendapat pemeriksaan dan konversi yang sama seperti unggahan baru, dan versi sebelumnya dihapus. Memerlukan API key lengkap; 404 jika unggahan tidak ada di akun Anda, 409 jika dilindungi kata sandi atau dibatasi jumlah tayangnya.

curl -X POST https://yourimageshare.com/api/aB3xY9qRz1/replace \
  -H "X-API-Key: YOUR_API_KEY" -F [email protected]

GET /api - Daftar Unggahan Anda

Mengembalikan daftar unggahan akun yang terautentikasi dengan paginasi (dari sumber mana pun - API, situs web, atau editor), terbaru lebih dulu, 50 per halaman.

Respons - 200 OK:

{
  "type": "success",
  "data": [
    {
      "id": "aB3xY9qRz1",
      "type": "image",
      "title": null,
      "path": "https://i.yourimageshare.com/aB3xY9qRz1.webp",
      "src": "https://yourimageshare.com/ib/aB3xY9qRz1.webp",
      "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
      "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
      "width": 1920,
      "height": 1080,
      "size": 482113,
      "locked": false,
      "visibility": "unlisted",
      "description": null,
      "expires_at": null,
      "created_at": "2026-07-23T15:43:28+01:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Field di sini bermakna sama seperti pada respons unggah di atas (untuk unggahan yang dilindungi kata sandi, path dan thumb berupa link bertanda tangan yang berlaku singkat). Belum ada endpoint tunggal untuk "mengambil satu unggahan", jadi daftar ini juga menjadi cara untuk mencari id sebuah file setelahnya.

DELETE /api/{id} - Hapus Unggahan

Menghapus permanen salah satu unggahan akun yang terautentikasi. Ini tidak dapat dibatalkan dari API. {id} adalah nilai yang dikembalikan sebagai id oleh endpoint unggah atau daftar.

Respons - 200 OK:

{ "type": "success", "msg": "Deleted." }

404 jika tidak ada unggahan dengan id tersebut di akun Anda (entah memang bukan milik Anda, atau sudah dihapus).

Batas Laju

Setiap API key memiliki kuota per menit dan per hari yang independen, ditambah batas harian per IP yang lebih longgar sebagai pengaman agar satu IP tidak berganti-ganti banyak key. Unggah, daftar, dan hapus berbagi batas yang sama.

Batas ini dapat berubah. Setiap respons menyertakan header batas laju standar:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14

429 dikembalikan ketika batas terlampaui, dengan header Retry-After yang memberi tahu berapa detik Anda harus menunggu.

Error

Setiap respons error memakai bentuk yang sama, apa pun endpoint atau penyebabnya:

{ "type": "error", "errors": "A human-readable description of what went wrong." }

Pustaka Klien

SDK resmi yang membungkus endpoint di atas dengan hasil bertipe dan memunculkan exception pada error API, bukan penanganan HTTP mentah.

JavaScript / TypeScript

Tanpa dependensi, berjalan di Node.js dan browser. Juga tersedia di JSR sebagai @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - sumber yang sama, diterbitkan langsung sebagai TypeScript.

npm install yourimageshare

Python

Satu dependensi (requests), Python 3.8+.

pip install yourimageshare

PHP

Tanpa dependensi Composer (memakai ekstensi curl bawaan PHP), PHP 7.4+. Sumber di GitHub.

composer require yourimageshare/yourimageshare-php

Go

Tanpa dependensi (hanya pustaka standar), Go 1.18+. Lihat pkg.go.dev untuk dokumentasi referensi lengkap.

go get github.com/yourimageshare/yourimageshare/go

Rust

Dua dependensi (ureq untuk HTTP blocking - tanpa runtime async - ditambah serde), Rust 1.70+. Sumber di GitHub.

cargo add yourimageshare

Ruby

Tanpa dependensi gem (stdlib Net::HTTP + json), Ruby 2.7+. Sumber di GitHub.

gem install yourimageshare

.NET

Satu dependensi (System.Text.Json dari Microsoft sendiri), menargetkan netstandard2.0 sehingga berjalan di .NET Framework maupun .NET modern. Sumber di GitHub. Dibangun dan diverifikasi terhadap API langsung ini; segera diterbitkan ke NuGet.

dotnet add package YourImageShare

Dart / Flutter

Satu dependensi (http, paket resmi tim Dart), Dart 2.17+. Sumber di GitHub. Dibangun dan diverifikasi terhadap API langsung ini; segera diterbitkan ke pub.dev.

dart pub add yourimageshare

Elixir

Satu dependensi (Req), Elixir 1.14+. Mengembalikan tuple bertanda {:ok, result}| {:error, reason} - padanan langsung dari penanganan error API ini di semua SDK lain - ditambah varian bang yang memunculkan exception. Sumber di GitHub, dokumentasi di HexDocs.

{:yourimageshare, "~> 1.1"}

MCP Server

Untuk agen pengodean AI (Claude Code, Cursor, dan alat lain yang kompatibel dengan MCP) - tempelkan tangkapan layar ke laporan bug, deskripsi PR, atau percakapan dukungan sebagai link sungguhan, bukan blob base64 atau langkah unggah manual. Bekerja dengan cara yang sama di Claude Desktop dan klien MCP lainnya. Jalankan langsung dengan npx, tanpa langkah instalasi:

npx yourimageshare-mcp

Tool: upload_image (file lokal, konten inline, atau link, hingga 200MB, dengan visibilitas, judul, dan hapus otomatis opsional), list_uploads, get_upload, update_upload, dan delete_upload.

Juga ada di MCP Registry resmi (sebagai io.github.yourimageshare/yourimageshare) dan terdaftar di Smithery serta Glama, jika klien MCP Anda menginstal dari salah satunya.

Baru mengenal MCP? Lihat cara menghubungkan Claude dan ChatGPT ke API ini lewat MCP untuk panduan pengaturan lengkap.

Contoh Kode

curl

# Upload a file
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg"

# Upload from a link (files up to 200MB; one direct upload request stops at 100MB -
# bigger files go in pieces, see Large Files above)
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "url=https://example.com/video.mp4"

# Upload a file that auto-deletes after 1 hour
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "expires_in=3600"

# List uploads
curl "https://yourimageshare.com/api" -H "X-API-Key: YOUR_API_KEY"

# Upload a file without a page of its own (file only) and give it a title
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "visibility=private" \
  -F "title=Sunset"

# Look up one upload, then make it public
curl "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"
curl -X PATCH "https://yourimageshare.com/api/aB3xY9qRz1" \
  -H "X-API-Key: YOUR_API_KEY" -d "visibility=public"

# Delete an upload
curl -X DELETE "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"

JavaScript (fetch)

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://yourimageshare.com/api';

async function uploadFile(file) {
  const form = new FormData();
  form.append('uploads', file);

  const res = await fetch(BASE, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: form,
  });
  const json = await res.json();
  if (json.type !== 'success') throw new Error(json.errors);
  return json.data;
}

async function listUploads(page = 1) {
  const res = await fetch(`${BASE}?page=${page}`, {
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

async function deleteUpload(id) {
  const res = await fetch(`${BASE}/${id}`, {
    method: 'DELETE',
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

Python (requests)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://yourimageshare.com/api"

HEADERS = {"X-API-Key": API_KEY}

# Upload a file
with open("/path/to/photo.jpg", "rb") as f:
    res = requests.post(BASE, headers=HEADERS, files={"uploads": f})
res.raise_for_status()
upload = res.json()["data"]

# List uploads
res = requests.get(BASE, headers=HEADERS, params={"page": 1})
uploads = res.json()

# Delete an upload
res = requests.delete(f"{BASE}/{upload['id']}", headers=HEADERS)

PHP (curl)

<?php

$apiKey = 'YOUR_API_KEY';
$base = 'https://yourimageshare.com/api';

// Upload a file
$curl = curl_init($base);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_POSTFIELDS => ['uploads' => new CURLFile('/path/to/photo.jpg')],
    CURLOPT_RETURNTRANSFER => true,
]);
$upload = json_decode(curl_exec($curl), true)['data'];
curl_close($curl);

// List uploads
$curl = curl_init("$base?page=1");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$uploads = json_decode(curl_exec($curl), true);
curl_close($curl);

Go (net/http)

SDK Go resmi di atas sudah membungkus ini untuk Anda - versi mentah ini disediakan bagi yang tidak ingin menambahkan dependensi.

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

const apiKey = "YOUR_API_KEY"
const base = "https://yourimageshare.com/api"

func uploadFile(path string) (map[string]any, error) {
    file, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("uploads", path)
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", base, body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("X-API-Key", apiKey)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    var result map[string]any
    json.NewDecoder(res.Body).Decode(&result)
    return result, nil
}

Alat Tangkapan Layar

Ekstensi browser plus konfigurasi dan skrip siap pakai untuk mengirim tangkapan layar langsung ke YourImageShare, tanpa unggah manual. Masing-masing mengunggah lewat endpoint /api yang sama seperti yang didokumentasikan di atas.

Ekstensi Browser (Chrome & Firefox)

Ekstensi YourImageShare Capture untuk Chrome dan Firefox tidak memerlukan skrip maupun file konfigurasi sama sekali. Ekstensi ini menangkap area yang terlihat, area yang dipilih dengan seret, atau satu halaman penuh yang digulir, membuka editor bawaan untuk panah, teks, blur/sensor, dan anotasi lainnya, lalu mengunduh hasilnya, menyalinnya ke clipboard, atau menerbitkannya langsung ke YourImageShare dengan satu klik. Penerbitan memakai endpoint /api yang sama seperti didokumentasikan di atas - tambahkan API key Anda sekali di Pengaturan ekstensi dan setiap penerbitan setelahnya langsung mengembalikan link yang bisa dibagikan. Berfungsi di Chrome desktop (dan browser Chromium lainnya), Firefox desktop, dan Firefox untuk Android.

Dapatkan YourImageShare Capture untuk Firefox Dapatkan YourImageShare Capture untuk Chrome

ShareX

Unduh custom uploader di bawah, lalu di ShareX buka Destinations > Custom uploader settings > Import > from file, pilih file .sxcu yang diunduh, dan ganti YOUR_API_KEY di kolom Headers dengan key asli Anda. Atur sebagai tujuan gambar/file dan tangkapan akan terunggah otomatis.

Unduh YourImageShare.sxcu

Flameshot (Linux)

Skrip shell kecil yang menjalankan flameshot gui, mengunggah tangkapan, dan menyalin link ke clipboard Anda. Kaitkan ke pintasan keyboard di lingkungan desktop Anda sebagai pengganti pintasan bawaan Flameshot.

Unduh yis-flameshot-upload.sh

# One-time setup
chmod +x yis-flameshot-upload.sh
export YIS_API_KEY="YOUR_API_KEY"   # or add to ~/.config/yourimageshare/api_key

# Then bind this to a hotkey instead of calling flameshot directly:
/path/to/yis-flameshot-upload.sh

Greenshot (Windows)

Skrip PowerShell untuk tujuan External command bawaan Greenshot. Kompatibel dengan Windows PowerShell 5.1 yang disertakan di Windows, tanpa instalasi tambahan.

Unduh yis-greenshot-upload.ps1

# One-time setup
setx YIS_API_KEY "YOUR_API_KEY"

# In Greenshot: Preferences > Destinations > External command > Settings
#   Command:   powershell.exe
#   Arguments: -ExecutionPolicy Bypass -File "C:\path\to\yis-greenshot-upload.ps1" "%1"

Plugin Forum

Tambahkan tombol "Unggah Gambar" sungguhan di samping editor posting forum Anda. Masing-masing mengunggah lewat endpoint /api yang sama seperti didokumentasikan di atas dan menyisipkan BBCode di posisi kursor - tanpa tab terpisah, tanpa salin-tempel manual.

Unggahan forum secara bawaan bersifat private: gambar berfungsi di dalam posting, tetapi YourImageShare tidak memberinya halaman tersendiri (tanpa komentar, reaksi, atau iklan). Setiap plugin memiliki pengaturan untuk beralih ke unlisted jika Anda juga menginginkan halaman bagi siapa pun yang memiliki link.

phpBB

Ekstensi phpBB 3.2/3.3 sungguhan. Ekstrak ke ext/, aktifkan di Customise > Manage extensions, lalu ganti YOUR_UPLOAD_ONLY_KEY di file event template ekstensi dengan key khusus unggah asli Anda.

Unduh untuk phpBB

SMF (Simple Machines Forum)

Paket SMF sungguhan - instal lewat Admin > Package Manager, lalu ganti YOUR_UPLOAD_ONLY_KEY di Sources/yis_forumupload.php dengan key khusus unggah asli Anda.

Unduh untuk SMF

MyBB

Plugin MyBB 1.8 sungguhan. Salin ke inc/plugins/, aktifkan di Configuration > Plugins, lalu ganti YOUR_UPLOAD_ONLY_KEY di file plugin dengan key khusus unggah asli Anda.

Unduh untuk MyBB

FluxBB, PunBB & ZetaBoards

Platform ini tidak memiliki sistem plugin resmi, jadi berupa cuplikan kecil yang ditempel langsung ke template Anda (FluxBB/PunBB) atau Admin CP (ZetaBoards) - petunjuk salin-tempel lengkap untuk masing-masing:

Petunjuk FluxBB Petunjuk PunBB Petunjuk ZetaBoards

Plugin WordPress

Pindahkan Pustaka Media Anda ke YourImageShare alih-alih disk lokal. Unggahan gambar/video baru otomatis melewati endpoint /api yang sama seperti didokumentasikan di atas, file lokal (dan setiap ukuran thumbnail yang dihasilkan) dihapus setelah unggahan dikonfirmasi, dan setiap URL lampiran WordPress - editor blok, gambar unggulan, galeri, REST API - mengarah ke file yang dihosting di YourImageShare. Tanpa shortcode, tanpa perubahan alur kerja.

• Pindahkan Pustaka Media yang sudah ada secara massal di latar belakang (atau dengan wp yis offload --all), bukan hanya unggahan baru
• Gambar dan video yang sudah ada di dalam posting tetap berfungsi setelah file lokalnya dihapus
• Thumbnail dan srcset memakai thumbnail 280px kami, sehingga slot gambar kecil tidak memuat file ukuran penuh
• File hingga 200MB, dikirim per bagian agar video besar tidak membebani shared hosting
• Kembalikan file yang sudah dipindahkan ke penyimpanan lokal kapan saja
• Kolom di Pustaka Media menunjukkan mana yang sudah dipindahkan dan mana yang masih lokal
• File yang dipindahkan disimpan sebagai private: tampil di mana pun situs Anda memakainya, tetapi tidak mendapat halaman tersendiri di YourImageShare

Dapatkan di WordPress.org Unduh file ZIP

Di WordPress: Plugins > Add New, cari YourImageShare Media Offload, lalu Install dan Activate.

Dari Blog