API dokumentacija

Dobivanje API ključa

Prijavite se, otvorite Moj račun i kliknite karticu API. Ondje je prikazan vaš ključ, zajedno s gumbom Generiraj ponovno. Ponovnim generiranjem stari ključ odmah prestaje vrijediti, zato prije klika ažurirajte sva mjesta na kojima se koristi.

Ista kartica sadrži i drugi, neovisni ključ samo za učitavanje - pogledajte savjet u nastavku i dodatke za forume da vidite kada ga koristiti umjesto glavnog.

Autentikacija

Ključ pošaljite kao zaglavlje - to je preporučeni način jer upiti u URL-u često završe u zapisnicima pristupa, zapisnicima proxyja i zaglavljima Referer:

X-API-Key: YOUR_API_KEY

Radi i parametar upita ?key=, koji je zadržan radi kompatibilnosti sa starijim integracijama i brzih jednokratnih curl naredbi. Ako su prisutni oba, prednost ima zaglavlje.

?key=YOUR_API_KEY

Endpointi

Učitavanje, popis i brisanje dijele istu autentikaciju i ograničenja; velike datoteke mogu se prethodno poslati u dijelovima.

POST /api - učitavanje datoteke

Učitava jednu datoteku za prijavljeni račun.

Prihvaćene vrste: JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC ili HEIF slike; MP4, WEBM ili AVI video (točan popis može se s vremenom proširiti). HEIC/HEIF i TIFF spremaju se kao WebP, video koji nije MP4/WebM pretvara se u MP4, a veće JPEG/PNG slike pretvaraju se u WebP ubrzo nakon učitavanja kada ih to osjetno smanjuje. Najveća veličina: 200MB; prevelike ili nečitljive datoteke odbijaju se s pogreškom 422.

Odgovor - 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 - velike datoteke

Jedan zahtjev može nositi najviše 100MB. Za veće datoteke (do 200MB) ili da svaki zahtjev ostane malen na sporoj vezi, pošaljite datoteku u dijelovima od najviše 5MB, a zatim završite pomoću POST /api:

1. Odaberite ID učitavanja: 32 nasumična heksadecimalna znaka.
2. Za svaki dio pošaljite POST /api/chunk (multipart/form-data) s upload_id, index (od 0), total (broj dijelova) i bajtovima u polju chunk. Odgovor je {"type": "success", "chunk_size": 5242880}.
3. POST /api s upload_id i filename umjesto uploads, plus sva ostala polja učitavanja. Odgovor je uobičajeni odgovor na učitavanje.

Dijelovi nedovršenog učitavanja brišu se nakon 2 sata. Samo završni POST /api ulazi u ograničenja učitavanja.

GET /api/{id} i PATCH /api/{id} - jedno učitavanje

GET vraća jedno vaše učitavanje s istim poljima kao popis u nastavku. PATCH mijenja njegov visibility, title ili description (polja obrasca ili JSON; prazan naslov ili opis briše ga) i vraća ažurirano učitavanje. Oba zahtijevaju puni API ključ; 404 ako takvog učitavanja nema na vašem računu.

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 - zamjena datoteke

Zamjenjuje datoteku iza jednog vašeg učitavanja, a zadržava njegov ID, stranicu i sve poveznice. Radi bilo koja dopuštena vrsta, čak i drukčija (slika može postati video). Novu datoteku pošaljite kao uploads (ili upload_id datoteke poslane u dijelovima pomoću POST /api/chunk); keep_original radi kao kod učitavanja. Nova datoteka prolazi iste provjere i pretvorbe kao novo učitavanje, a prethodna se verzija uklanja. Zahtijeva puni API ključ; 404 ako takvog učitavanja nema na vašem računu, 409 ako je zaštićeno lozinkom ili ima ograničen broj pregleda.

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

GET /api - popis vaših učitavanja

Vraća straničen popis učitavanja prijavljenog računa (iz bilo kojeg izvora - API-ja, web-mjesta ili uređivača), od najnovijih, 50 po stranici.

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

Polja ovdje znače isto što i u gornjem odgovoru na učitavanje (za učitani sadržaj zaštićen lozinkom path i thumb kratkotrajne su potpisane poveznice). Zasebnog endpointa za dohvat jednog učitavanja još nema, pa je ovaj popis ujedno način da naknadno pronađete id datoteke.

DELETE /api/{id} - brisanje učitavanja

Trajno briše jedno učitavanje prijavljenog računa. To se putem API-ja ne može poništiti. {id} je vrijednost vraćena kao id iz endpointa za učitavanje ili popis.

Odgovor - 200 OK:

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

404 ako na vašem računu ne postoji učitavanje s tim ID-jem (ili nikad nije bilo vaše ili je već izbrisano).

Ograničenja

Svaki API ključ ima neovisne kvote po minuti i po danu, uz grublje dnevno ograničenje po IP adresi kao zaštitu od toga da jedna IP adresa izmjenjuje više ključeva. Učitavanja, popisi i brisanja dijele ista ograničenja.

Ova se ograničenja mogu promijeniti. Svaki odgovor sadrži standardna zaglavlja o ograničenjima:

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

Kada se ograničenje prekorači, vraća se 429 sa zaglavljem Retry-After koje kaže koliko sekundi treba pričekati.

Pogreške

Svaki odgovor s pogreškom ima isti oblik, bez obzira na endpoint ili uzrok:

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

Klijentske biblioteke

Službeni SDK-ovi koji omataju gornje endpointe tipiziranim rezultatima i podižu iznimku kod pogrešaka API-ja umjesto ručnog rukovanja HTTP-om.

JavaScript / TypeScript

Bez ovisnosti, radi u Node.js-u i preglednicima. Dostupno i na JSR-u kao @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - isti izvorni kod, objavljen izravno kao TypeScript.

npm install yourimageshare

Python

Jedna ovisnost (requests), Python 3.8+.

pip install yourimageshare

PHP

Bez Composer ovisnosti (koristi PHP-ovo vlastito proširenje curl), PHP 7.4+. Izvorni kod na GitHubu.

composer require yourimageshare/yourimageshare-php

Go

Bez ovisnosti (samo standardna biblioteka), Go 1.18+. Cjelovitu referentnu dokumentaciju pogledajte na pkg.go.dev.

go get github.com/yourimageshare/yourimageshare/go

Rust

Dvije ovisnosti (ureq za blokirajući HTTP - bez povlačenja asinkronog runtimea - plus serde), Rust 1.70+. Izvorni kod na GitHubu.

cargo add yourimageshare

Ruby

Bez ovisnosti o gemovima (standardni Net::HTTP + json), Ruby 2.7+. Izvorni kod na GitHubu.

gem install yourimageshare

.NET

Jedna ovisnost (Microsoftov System.Text.Json), cilja netstandard2.0 pa radi i iz .NET Frameworka i iz modernog .NET-a. Izvorni kod na GitHubu. Izrađeno i provjereno na ovom živom API-ju; objava na NuGetu uskoro.

dotnet add package YourImageShare

Dart / Flutter

Jedna ovisnost (http, paket samog Dart tima), Dart 2.17+. Izvorni kod na GitHubu. Izrađeno i provjereno na ovom živom API-ju; objava na pub.dev uskoro.

dart pub add yourimageshare

Elixir

Jedna ovisnost (Req), Elixir 1.14+. Vraća {:ok, result}| {:error, reason} označene n-torke - izravni ekvivalent rukovanja pogreškama ovog API-ja u svim ostalim SDK-ovima - plus varijante s uskličnikom koje podižu iznimku. Izvorni kod na GitHubu, dokumentacija na HexDocsu.

{:yourimageshare, "~> 1.1"}

MCP server

Za AI agente za programiranje (Claude Code, Cursor i drugi alati kompatibilni s MCP-om) - umetnite snimku zaslona u prijavu greške, opis PR-a ili nit podrške kao pravi URL umjesto base64 zapisa ili ručnog učitavanja. Radi jednako s Claude Desktopom i bilo kojim drugim MCP klijentom. Pokrenite izravno pomoću npx, bez instalacije:

npx yourimageshare-mcp

Alati: upload_image (lokalna datoteka, ugrađeni sadržaj ili poveznica, do 200MB, uz neobavezne postavke vidljivosti, naslova i automatskog brisanja), list_uploads, get_upload, update_upload i delete_upload.

Također u službenom MCP registru (kao io.github.yourimageshare/yourimageshare) te na Smitheryju i Glami, ako se vaš MCP klijent instalira s jednog od njih.

Novi ste u MCP-u? Pogledajte kako povezati Claude i ChatGPT s ovim API-jem putem MCP-a za cjelovit vodič kroz postavljanje.

Primjeri koda

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)

Službeni Go SDK iznad to radi umjesto vas - ova sirova verzija tu je za one koji ne žele dodavati ovisnost.

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
}

Alati za snimke zaslona

Proširenje za preglednik te gotove konfiguracije i skripte za slanje snimaka zaslona izravno na YourImageShare, bez ručnog učitavanja. Svaki učitava preko istog /api endpointa opisanog iznad.

Proširenje za preglednik (Chrome i Firefox)

Proširenje YourImageShare Capture za Chrome i Firefox u potpunosti zaobilazi skripte i konfiguracijske datoteke. Snima vidljivo područje, ručno odabrani dio ili cijelu stranicu koja se pomiče, otvara ugrađeni uređivač za strelice, tekst, zamućivanje/zacrnjivanje i druge bilješke, a zatim preuzima rezultat, kopira ga u međuspremnik ili ga jednim klikom objavljuje izravno na YourImageShare. Objava koristi isti /api endpoint opisan iznad - jednom dodajte svoj API ključ u postavkama proširenja i svaka sljedeća objava odmah vraća poveznicu za dijeljenje. Radi u računalnom Chromeu (i drugim Chromium preglednicima), računalnom Firefoxu i Firefoxu za Android.

Preuzmite YourImageShare Capture za Firefox Preuzmite YourImageShare Capture za Chrome

ShareX

Preuzmite prilagođeni uploader u nastavku, zatim u ShareX-u idite na Destinations > Custom uploader settings > Import > from file, otvorite preuzeti .sxcu i zamijenite YOUR_API_KEY u polju Headers svojim pravim ključem. Postavite ga kao odredište za slike/datoteke i snimke će se učitavati automatski.

Preuzmite YourImageShare.sxcu

Flameshot (Linux)

Mala shell skripta koja pokreće flameshot gui, učitava snimku i kopira poveznicu u međuspremnik. Povežite je s tipkovničkim prečacem u svom desktop okruženju umjesto Flameshotova zadanog.

Preuzmite 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)

PowerShell skripta za Greenshotovo ugrađeno odredište External command. Kompatibilna s Windows PowerShellom 5.1 koji dolazi uz Windows, bez dodatne instalacije.

Preuzmite 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"

Dodaci za forume

Dodajte pravi gumb "Učitaj sliku" pored uređivača objava na vašem forumu. Svaki učitava preko istog /api endpointa opisanog iznad i umeće BBCode na položaj kursora - bez zasebne kartice, bez ručnog kopiranja i lijepljenja.

Učitavanja s foruma prema zadanim su postavkama privatna: slika radi u objavi, ali joj YourImageShare ne daje zasebnu stranicu (bez komentara, reakcija i oglasa). Svaki dodatak ima postavku za prelazak na unlisted ako želite i stranicu za svakoga s poveznicom.

phpBB

Pravo proširenje za phpBB 3.2/3.3. Raspakirajte u ext/, omogućite ga pod Customise > Manage extensions, a zatim zamijenite YOUR_UPLOAD_ONLY_KEY u datoteci događaja predloška proširenja svojim pravim ključem samo za učitavanje.

Preuzmite za phpBB

SMF (Simple Machines Forum)

Pravi SMF paket - instalirajte ga preko Admin > Package Manager, a zatim zamijenite YOUR_UPLOAD_ONLY_KEY u Sources/yis_forumupload.php svojim pravim ključem samo za učitavanje.

Preuzmite za SMF

MyBB

Pravi dodatak za MyBB 1.8. Kopirajte u inc/plugins/, aktivirajte pod Configuration > Plugins, a zatim zamijenite YOUR_UPLOAD_ONLY_KEY u datoteci dodatka svojim pravim ključem samo za učitavanje.

Preuzmite za MyBB

FluxBB, PunBB i ZetaBoards

Oni nemaju formalni sustav dodataka, pa je riječ o malom isječku koji se lijepi izravno u vaš predložak (FluxBB/PunBB) ili Admin CP (ZetaBoards) - potpune upute za kopiranje i lijepljenje za svaki:

Upute za FluxBB Upute za PunBB Upute za ZetaBoards

WordPress dodatak

Prebacite svoju medijsku knjižnicu na YourImageShare umjesto na lokalni disk. Nova učitavanja slika/videa automatski idu preko istog /api endpointa opisanog iznad, lokalna datoteka (i svaka generirana veličina sličice) briše se nakon potvrde učitavanja, a svaki URL WordPress privitka - blok-uređivač, istaknute slike, galerije, REST API - vodi na datoteku smještenu na YourImageShareu. Bez shortcodea, bez promjene načina rada.

• Skupno prebacivanje postojeće medijske knjižnice u pozadini (ili pomoću wp yis offload --all), a ne samo novih učitavanja
• Slike i videi već umetnuti u objave nastavljaju raditi nakon uklanjanja lokalnih datoteka
• Sličice i srcset koriste našu sličicu od 280px, pa mala mjesta za slike ne učitavaju datoteke pune veličine
• Datoteke do 200MB, slane u dijelovima kako veliki videi nikad ne opterete zajednički hosting
• Bilo koju prebačenu datoteku u bilo kojem trenutku možete vratiti u lokalnu pohranu
• Stupac u medijskoj knjižnici prikazuje što je prebačeno, a što je još lokalno
• Prebačene datoteke spremaju se kao privatne: učitavaju se gdje god ih vaše web-mjesto koristi, ali nemaju zasebnu stranicu na YourImageShareu

Preuzmite s WordPress.org Preuzmite ZIP

U WordPressu: Plugins > Add New, potražite YourImageShare Media Offload, zatim kliknite Install i Activate.

S bloga