Public API

1) Authentifizierung

Erstelle zuerst in den Benutzereinstellungen einen API-Schlüssel und sende ihn pro Request im Header X-API-Key.

export BASE_URL="https://pixelfox.cc"
export API_KEY="DEIN_API_KEY"

curl -sS "$BASE_URL/api/v1/user/profile" \
  -H "X-API-Key: $API_KEY" | jq

Alternative Header-Variante: Authorization: Bearer DEIN_API_KEY.

2) Upload-Session erzeugen

Vor jedem Upload wird ein zeitlich begrenztes Token ausgestellt. Zusätzlich kannst du pro Upload festlegen, welche Derivate erzeugt werden sollen. Das Original bleibt immer erhalten. Mit album_id kannst du den Upload direkt in ein bestehendes eigenes Album einsortieren. Mit is_nsfw markierst du den Upload als sensiblen Inhalt.

export FILE="./beispiel.jpg"
export FILE_SIZE=$(wc -c < "$FILE")
export ALBUM_ID=42

SESSION_JSON=$(curl -sS -X POST "$BASE_URL/api/v1/upload/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{
    \"file_size\": $FILE_SIZE,
    \"album_id\": $ALBUM_ID,
    \"is_nsfw\": true,
    \"processing\": {
      \"profile\": \"custom\",
      \"derivatives\": [
        { \"family\": \"webp\", \"size\": \"small\" },
        { \"family\": \"avif\", \"size\": \"small\" }
      ]
    }
  }")

echo "$SESSION_JSON" | jq
UPLOAD_URL=$(echo "$SESSION_JSON" | jq -r '.upload_url')
UPLOAD_TOKEN=$(echo "$SESSION_JSON" | jq -r '.token')

Lasse processing weg, wenn du die aktuellen User-Defaults verwenden willst. Mit profile=original_only wird nur das Original gespeichert. Lasse album_id weg, wenn der Upload keinem Album zugeordnet werden soll. Lasse is_nsfw weg, um den NSFW-Default aus deinen Einstellungen zu verwenden, oder setze es explizit auf false bzw. true für diesen Upload.

Processing-Profile

// Gleichbedeutend mit den aktuellen User-Defaults
{ "file_size": 1837421 }

// In ein bestehendes Album hochladen
{
  "file_size": 1837421,
  "album_id": 42,
  "is_nsfw": true
}

// Nur das Original behalten
{
  "file_size": 1837421,
  "processing": {
    "profile": "original_only"
  }
}

// Exakt kleine WebP- und AVIF-Varianten anfordern
{
  "file_size": 1837421,
  "processing": {
    "profile": "custom",
    "derivatives": [
      { "family": "webp", "size": "small" },
      { "family": "avif", "size": "small" }
    ]
  }
}

In Antworten kann bei älteren Bildern zusätzlich profile=legacy auftauchen. Das ist nur ein Rückwärtskompatibilitätswert für Uploads vor der neuen per-Request-Policy.

3) Bild hochladen und Resource abrufen

Lade die Datei per Multipart-Form an die upload_url aus Schritt 2 hoch. Anschließend prüfst du den Status und holst dir die finale Resource.

UPLOAD_RESULT=$(curl -sS -X POST "$UPLOAD_URL" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -F "file=@$FILE")

echo "$UPLOAD_RESULT" | jq
IMAGE_UUID=$(echo "$UPLOAD_RESULT" | jq -r '.image_uuid')

curl -sS "$BASE_URL/api/v1/images/$IMAGE_UUID/status" \
  -H "X-API-Key: $API_KEY" | jq

curl -sS "$BASE_URL/api/v1/images/$IMAGE_UUID" \
  -H "X-API-Key: $API_KEY" | jq