Upload Mediów

Upload mediów (zrzuty ekranu, obrazy) odbywa się w 4 krokach z wykorzystaniem presigned URL. Pliki są przechowywane w Backblaze B2.

Wymagany scope: media:write

Proces uploadu

mermaid

sequenceDiagram
    participant C as Twoja aplikacja
    participant A as API clarife
    participant S as Storage (B2)

    C->>A: POST /media/presign
    A-->>C: upload_url + media_id
    C->>S: PUT upload_url (plik binarny)
    S-->>C: 200 OK
    C->>A: POST /media/confirm
    A-->>C: { id, status: "active" }
    C->>A: PATCH /documents/:id (dodaj blok screenshot)
    A-->>C: { id, updated_at }

Krok 1: Uzyskaj presigned URL

bash

curl -s -X POST https://my.clarife.app/api/v1/media/presign \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "d1234567-...",
    "media_id": "m1234567-...",
    "filename": "screenshot.png",
    "mime_type": "image/png",
    "file_size_bytes": 245760
  }' | jq

Parametry body:

Pole	Typ	Wymagane	Opis
document_id	uuid	tak	Dokument, do którego dodajesz media
media_id	uuid	tak	UUID v4 wygenerowane po stronie klienta
filename	string	tak	Oryginalna nazwa pliku (max 255 znaków)
mime_type	string	tak	Typ MIME (patrz tabela poniżej)
file_size_bytes	integer	tak	Dokładny rozmiar pliku w bajtach

Obsługiwane typy MIME (tylko obrazy):

Typ	Rozszerzenie
image/png	.png
image/jpeg	.jpg
image/jpg (wariant niestandardowy)	.jpg
image/gif	.gif
image/webp	.webp
image/svg+xml	.svg
image/bmp	.bmp
image/tiff	.tiff

Odpowiedź 201 Created:

json

{
  "data": {
    "upload_url": "https://s3.eu-central-003.backblazeb2.com/...",
    "media_id": "m1234567-..."
  }
}

⚠️ Uwaga: Maksymalny rozmiar pliku to 30 MB. Presigned URL jest ważny przez 15 minut.

Krok 2: Upload pliku

Wyślij plik binarny na upload_url zwrócony w kroku 1 za pomocą PUT z nagłówkiem Content-Length:

bash

curl -X PUT "UPLOAD_URL_Z_KROKU_1" \
  -H "Content-Length: 245760" \
  --data-binary @screenshot.png

⚠️ Uwaga: Nagłówek Content-Length musi dokładnie odpowiadać wartości file_size_bytes z kroku 1.

Krok 3: Potwierdź upload

Po pomyślnym uploadzie potwierdź, że plik jest gotowy:

bash

curl -s -X POST https://my.clarife.app/api/v1/media/confirm \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "media_id": "m1234567-..." }' | jq

Odpowiedź 200 OK:

json

{
  "data": {
    "id": "m1234567-...",
    "status": "active"
  }
}

Krok 4: Podlinkuj w dokumencie

Po potwierdzeniu uploadu dodaj blok screenshot z media_id do treści dokumentu. Musisz wysłać pełną tablicę blocks (najpierw pobierz obecne bloki przez GET /documents/:id):

bash

curl -s -X PATCH https://my.clarife.app/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer clrf_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "meta": { "version": 1, "locale": "pl" },
      "blocks": [
        { "type": "heading", "id": "h1", "sort_order": 0, "level": 1, "content": "Mój tutorial" },
        { "type": "text", "id": "t1", "sort_order": 1, "content": "Oto zrzut ekranu:" },
        {
          "type": "screenshot",
          "id": "ss1-ekran",
          "sort_order": 2,
          "media_id": "m1234567-...",
          "caption": "Widok dashboardu",
          "alignment": "center"
        }
      ]
    }
  }' | jq

Blok screenshot wymaga:

Pole	Typ	Wymagane	Opis
type	string	tak	"screenshot" lub "image"
id	string	tak	Unikalne ID bloku w dokumencie
sort_order	integer	tak	Pozycja wyświetlania (od 0)
media_id	uuid	tak	media_id z kroku 1
caption	string	nie	Podpis pod obrazem
alignment	string	nie	"left", "center" lub "right" (domyślnie: "center")

Pełną dokumentację formatu bloków znajdziesz w API Dokumentów.

ℹ️ Informacja: Media ze statusem pending (niepotwierdzony upload) są automatycznie czyszczone po około 2 godzinach.

Limity storage

Plan	Limit storage
Free	100 MB
Pro	10 GB
Business	100 GB

Przekroczenie limitu zwraca błąd 403 z kodem PLAN_LIMIT_REACHED.