Przejdź do treści
Clevera Help Center

Korzystanie z REST API Clevera

Wywołuj Clevera z własnych skryptów: podstawowy adres URL, uwierzytelnianie bearer-token, punkty końcowe i wymagane uprawnienia, proces wyceny i uruchamiania płatnych zadań, idempotencja, format błędów oraz limity zapytań.

Zaktualizowano 8 min czytania

REST API Clevera pozwala Twoim własnym skryptom i usługom wykonywać zadania, które agent może realizować przez MCP: przeglądać bibliotekę, żądać filmów i artykułów, eksportować filmy, pracować nad witrynami dokumentacji i śledzić zadania. Ten artykuł omawia podstawowy adres URL, uwierzytelnianie, proces żądania płatnych prac, błędy oraz limity zapytań.

Podstawy
Podstawowy adres URL https://app.clevera.ai/api/v1
Uwierzytelnianie Authorization: Bearer <token> za pomocą tokena API (zaczyna się od clv_agent_)
Format JSON na wejściu i wyjściu. Wyślij Accept: application/json, a w przypadku treści, Content-Type: application/json.
Identyfikatory Publiczne identyfikatory, takie jak job_… dla zadań. Używaj identyfikatorów zwracanych przez API.

Sprawdź token za pomocą GET /docs/me:

Terminal
curl -H "Authorization: Bearer $CLEVERA_TOKEN" \
     -H "Accept: application/json" \
     https://app.clevera.ai/api/v1/docs/me

Odpowiedź informuje, w czyim imieniu działa token: nazwę i datę wygaśnięcia tokena, osobę i jej bieżącą rolę, obszar roboczy, witryny w zakresie oraz uprawnienia, które działają w tej chwili (uprawnienia tokena ograniczone do bieżącej roli osoby). Wywołaj to w pierwszej kolejności, gdy wywołanie zostanie odrzucone.

Punkty końcowe

Każdy punkt końcowy wymaga pokazanego uprawnienia. Wywołanie go bez odpowiedniego uprawnienia zwróci 403 forbidden_ability. Zobacz Uprawnienia agenta.

Biblioteka i materiały

Metoda i ścieżka Uprawnienie Działanie
GET /create/types dowolne Typy filmów i klipów społecznościowych, o które możesz poprosić.
GET /library library:read Filmy, nagrania i artykuły, które właściciel tokena może zobaczyć.
GET /recordings library:read Tylko nagrania.
GET /library/{item} library:read Jeden element.
GET /library/{item}/transcript library:read Jego transkrypcja.
GET /library/{item}/article library:read Jego artykuł.
GET /library/{item}/embed library:read Jego kod osadzenia.
GET /materials library:read Przesłane obrazy, filmy i pliki PDF.
POST /materials, POST /materials/import, POST /materials/uploads, POST /materials/uploads/{upload_id}/complete materials:write Dodaj obraz, film lub plik PDF (bezpośrednio, z adresu URL lub jako duże przesłanie).

Filmy i artykuły

Metoda i ścieżka Uprawnienie Działanie
POST /videos/quotes videos:create Wycena filmu z nagrania (type: how_to, product_demo, cleanup, styled_video), artykułu z nagrania (article) lub tłumaczenia (translation).
POST /videos videos:create + credits:spend Utwórz wyceniony film (quote_id).
POST /articles/from-recording videos:create + credits:spend Utwórz wyceniony artykuł.
POST /videos/translations videos:create + credits:spend Utwórz wycenione tłumaczenie.
POST /clips/quotes videos:create Wycena klipu społecznościowego (typy z GET /create/types).
POST /clips videos:create + credits:spend Utwórz wyceniony klip społecznościowy.
POST /videos/{video_id}/exports videos:export Renderuj MP4: resolution 1080p (domyślnie), 2k lub 4k; zawsze 60 kl./s. Bezpłatnie.

Zadania i kredyty

Metoda i ścieżka Uprawnienie Działanie
POST /quotes uprawnienie pracy Wycena dla dowolnego rodzaju zadania.
POST /jobs uprawnienie pracy (+ credits:spend jeśli płatne) Rozpocznij wycenione zadanie.
GET /jobs jobs:read Lista zadań.
GET /jobs/{job} jobs:read Status i wynik jednego zadania.
GET /jobs/{job}/wait jobs:read Czekaj na zmianę zamiast odpytywania.
GET /jobs/{job}/events jobs:read Zdarzenia postępu zadania.
POST /jobs/{job}/cancel jobs:read Anuluj zadanie. Zbyt późno: „Tego zadania nie można już anulować”.
GET /credits credits:spend lub jobs:read Saldo kredytów obszaru roboczego.

Witryny dokumentacji

Metoda i ścieżka Uprawnienie Działanie
GET /docs/sites, GET /docs/sites/{site}, GET /docs/sites/{site}/tree, GET /docs/sites/{site}/pages content:read Witryny w zakresie tokena i ich strony.
GET /docs/sites/{site}/search, GET /docs/pages/{page}, GET /docs/pages/{page}/revisions content:read Wyszukiwanie i czytanie stron, w tym wersji roboczych.
POST /docs/sites/{site}/articles, PATCH /docs/pages/{page}/article, POST /docs/pages/{page}/review articles:write Tworzenie i edycja artykułów roboczych, przesyłanie do recenzji. Artykuły opublikowane wymagają również site:publish.
PATCH /docs/pages/{page}, DELETE /docs/pages/{page}, POST /docs/sites/{site}/sections, PATCH /docs/sections/{section} structure:write Przenoszenie, zmiana nazw, ukrywanie i usuwanie stron; sekcje.
GET/POST /docs/sites/{site}/site-pages, PUT /docs/site-pages/{page}/body content:read / site-pages:write Strona główna, kontakt i strony prawne.
GET/POST /docs/sites/{site}/changelog, PATCH /docs/changelog/{entry} content:read / changelog:write Wpisy w dzienniku zmian jako wersje robocze.
POST /docs/media, POST /docs/media/uploads media:write Przesyłanie obrazów.
POST /docs/sites/{site}/publish, POST /docs/pages/{page}/ready, POST /docs/changelog/{entry}/publish site:publish Publikowanie tego, co widzą czytelnicy.
GET /insights/sites/{site}, …/gaps, …/feedback insights:read Wyszukiwanie luk, pytań bez odpowiedzi, opinii o stronie.
PATCH /docs/sites/{site}/settings, …/appearance, PUT …/navigation, POST …/redirects site:configure Ustawienia witryny.
POST /docs/sites sites:create Utwórz witrynę dokumentacji.

Więcej o agentach i witrynach dokumentacji: Połącz agentów AI ze swoimi witrynami dokumentacji.

Praca, która kosztuje kredyty, zawsze wymaga najpierw wyceny, a potem rozpoczęcia:

  1. Wycena. POST /videos/quotes (lub /clips/quotes) z tym, czego potrzebujesz. Odpowiedź zawiera quote_id i zakres kredytów. Wycena jest ważna przez 15 minut i można jej użyć raz.
  2. Opcjonalnie: test (dry-run). Wyślij rozpoczęcie z "dry_run": true, aby dowiedzieć się, czy zadanie by wystartowało, wymagało zatwierdzenia czy zostało zablokowane. Nic nie jest zapisywane.
  3. Rozpoczęcie. POST /videos z quote_id i nagłówkiem Idempotency-Key. Odpowiedź to 202 z zadaniem.
  4. Śledzenie. GET /jobs/{job}/wait, aż status zadania się zmieni, lub nasłuchuj webhooków.
Quote, then start a how-to video
curl -X POST https://app.clevera.ai/api/v1/videos/quotes \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "how_to", "recording_id": "<recording id>", "language": "en-US"}'

curl -X POST https://app.clevera.ai/api/v1/videos \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1a2e-8d4b-4f7a-9c1e-2b5d7e9f0a13" \
  -d '{"quote_id": "<quote id>"}'

Statusy zadań:

Status Znaczenie
queued Zaakceptowano, zaraz się uruchomi.
running W toku.
needs_input Czeka na osobę, zazwyczaj na zatwierdzenie w Żądania agenta. Zadanie zawiera link i datę wygaśnięcia.
succeeded Gotowe. Zadanie zawiera link do nowego filmu lub artykułu.
failed Niepowodzenie; zadanie zawiera error_code.
canceled Anulowano lub odmówiono zatwierdzenia.
expired Nikt nie zatwierdził w ciągu 24 godzin.

To, czy rozpoczęcie zadania następuje natychmiast, czy czeka na osobę, zależy od limitów wydatków tokena i ustawienia Zatwierdzaj automatycznie poniżej. Zobacz Kontroluj wydatki i zatwierdzenia agenta.

Ponawianie i idempotencja

Wyślij nagłówek Idempotency-Key (świeży UUID dla każdej akcji) przy każdym tworzeniu i rozpoczynaniu. Jeśli połączenie zostanie przerwane i ponowisz próbę z tym samym kluczem i treścią, otrzymasz pierwszą odpowiedź zamiast drugiego filmu. Klucze są zapamiętywane przez 24 godziny.

Kod Znaczenie
idempotency_key_reused Ten sam klucz z inną treścią. Użyj nowego klucza dla nowego żądania.
idempotency_in_progress Pierwsze żądanie z tym kluczem nadal działa. Poczekaj i ponów próbę.
idempotency_conflict „Ten klucz idempotencji został użyty dla innego żądania”.

Błędy

Każdy błąd ma ten sam format, z komunikatem informującym, co zrobić dalej:

{
  "error": {
    "code": "forbidden_ability",
    "message": "This token lacks the videos:create ability. Ask the workspace member who owns it for a token that has it.",
    "details": { "ability": "videos:create" }
  },
  "request_id": "req_example"
}

Podaj request_id podczas kontaktu z pomocą techniczną.

HTTP Kody Typowa przyczyna
401 unauthenticated, token_expired, token_revoked Brak tokena, błędny token, wygasły lub cofnięty token.
402 insufficient_credits Obszar roboczy nie ma wystarczającej liczby kredytów na wycenę.
403 forbidden_ability, forbidden_role, forbidden_item, ip_not_allowed, live_content_needs_publish, site_paused, forbidden Brak uprawnień, rola właściciela, dostęp do kolekcji lub lista dozwolonych adresów IP.
403 plan_locked „API agenta nie jest dostępne w planie tego obszaru roboczego. Wymagany plan Pro lub wyższy”.
404 not_found, unknown_kind „Brak … z tym identyfikatorem w zakresie tego tokena. Najpierw wyświetl listę lub wyszukaj i użyj zwróconego identyfikatora”.
409 revision_conflict, quote_used, not_cancelable, idempotency_* Treść uległa zmianie, wycena została wykorzystana lub wystąpił konflikt przy ponawianiu.
410 quote_expired „Ta wycena wygasła. Poproś o nową wycenę”.
413 unsupported_media Plik jest zbyt duży lub ma nieobsługiwany typ.
422 validation_failed, invalid_input, quote_mismatch, limit_reached Błędne pole; details wskazuje które.
429 rate_limited, cap_exceeded, busy Zbyt wiele żądań, limit wydatków lub dwa uruchomienia jednocześnie.

Każdy komunikat wraz z rozwiązaniem: Napraw błędy agenta i API.

Limity zapytań

Limit Wartość Komunikat
Żądania na token 300 na minutę „Ten token przekroczył limit szybkości żądań. Poczekaj i ponów próbę”.
Żądania na obszar roboczy 1200 na minutę, wszystkie tokeny łącznie „Ten obszar roboczy przekroczył limit szybkości żądań agenta. Poczekaj i ponów próbę”.
Zapisy na token 60 na minutę „Zbyt wiele zapisów z tego tokena. Poczekaj i ponów próbę”.
Zapisy na token dziennie 2000 „Ten token osiągnął dzienny limit zapisów. Spróbuj ponownie jutro”.
Publikacje na token 10 na godzinę „Ten token osiągnął godzinny limit publikacji. Spróbuj ponownie później”.
Płatne uruchomienia 20 na godzinę na token, 100 dziennie na obszar roboczy rate_limited z retry_after
Przesyłanie plików 30 na minutę; 500 MB dziennie na token; 25 MB na plik „Zbyt wiele przesłań z tego tokena. Poczekaj i ponów próbę.” / „Ten token osiągnął dzienny limit przesyłania. Spróbuj ponownie jutro”.
Wywołania bez ważnego tokena 60 na minutę na adres IP „Zbyt wiele żądań. Poczekaj i ponów próbę”.

Odpowiedź 429 zawiera nagłówek Retry-After oraz retry_after (sekundy) w treści. Odczekaj tyle czasu przed ponowieniem próby. Odczyty, wyceny i sprawdzanie statusu nie kosztują kredytów.

Utwórz token APIUzyskaj token dla swojego skryptu.Uprawnienia agentaJakie uprawnienia są wymagane dla każdego punktu końcowego.Skonfiguruj webhookiOtrzymuj powiadomienia o zakończonych zadaniach bez odpytywania.Napraw błędy agenta i APIKażdy błąd i jego rozwiązanie.