Dokumentacja API

Używaj tych endpointów REST Prompt Converter Cloud. Uwierzytelnij się kluczem API Cloud po subskrypcji.

Uwierzytelnianie

Wyślij Authorization: Bearer pc_cloud_… albo nagłówek X-Api-Key. Twórz klucze na stronie kluczy API po aktywnej subskrypcji Cloud. Nie wysyłaj JWT Supabase.

Adres bazowy

W produkcji użyj hosta Cloud, np. https://api.yourdomain.com. Lokalnie: http://localhost:5000.

Błędy

Nieudane żądania zwracają obiekt JSON z kodem błędu i opcjonalnym komunikatem.

{
  "error": "quota_exceeded",
  "message": "Optional human-readable detail"
}

Konwertuj prompt

POST /v1/convert

Konwertuje surowy tekst na zoptymalizowany prompt dla wybranego modelu. Dostępne we wszystkich planach Cloud i liczone do miesięcznego limitu konwersji.

Dostępne w: Wszystkie plany Cloud

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.
Content-Type string wymagane: Dla ciał JSON musi być application/json.

Parametry ciała

rawInput string wymagane: Tekst do konwersji lub jako tura czatu.
targetModel string opcjonalne: Klucz routingu: gpt, claude, gemini lub grok. Domyślnie gpt.
openAiResultModel string opcjonalne: Opcjonalny identyfikator modelu OpenAI z GET /v1/models, gdy targetModel to gpt.
claudeResultModel string opcjonalne: Opcjonalny identyfikator modelu Anthropic z GET /v1/models, gdy targetModel to claude.
geminiResultModel string opcjonalne: Opcjonalny identyfikator modelu Gemini z GET /v1/models, gdy targetModel to gemini.
grokResultModel string opcjonalne: Opcjonalny identyfikator modelu xAI Grok z GET /v1/models, gdy targetModel to grok.

Przykładowe żądanie

curl -X POST https://api.yourdomain.com/v1/convert \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"rawInput":"Explain dependency injection in .NET","targetModel":"gpt"}'

Odpowiedź sukcesu

{
  "result": "You are a senior .NET architect...",
  "targetModel": "gpt",
  "resultModel": "gpt-5.6-luna"
}

Błędy

400 raw_input_required, 401 missing_authorization / invalid_api_key, 403 subscription_required, 429 quota_exceeded, 502 provider_failed

Utwórz uzupełnienie czatu

POST /v1/chat

Wykonuje jednoturową kompletację czatu z tymi samymi polami modelu co convert. Tylko Growth i Business. Liczy się do limitu konwersji.

Dostępne w: Growth i Business

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.
Content-Type string wymagane: Dla ciał JSON musi być application/json.

Parametry ciała

rawInput string wymagane: Tekst do konwersji lub jako tura czatu.
targetModel string opcjonalne: Klucz routingu: gpt, claude, gemini lub grok. Domyślnie gpt.
openAiResultModel string opcjonalne: Opcjonalny identyfikator modelu OpenAI z GET /v1/models, gdy targetModel to gpt.
claudeResultModel string opcjonalne: Opcjonalny identyfikator modelu Anthropic z GET /v1/models, gdy targetModel to claude.
geminiResultModel string opcjonalne: Opcjonalny identyfikator modelu Gemini z GET /v1/models, gdy targetModel to gemini.
grokResultModel string opcjonalne: Opcjonalny identyfikator modelu xAI Grok z GET /v1/models, gdy targetModel to grok.

Przykładowe żądanie

curl -X POST https://api.yourdomain.com/v1/chat \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"rawInput":"Explain dependency injection","targetModel":"gpt","openAiResultModel":"gpt-5.6-luna"}'

Odpowiedź sukcesu

{
  "result": "Dependency injection is a technique...",
  "targetModel": "gpt",
  "resultModel": "gpt-5.6-luna"
}

Błędy

400 raw_input_required, 401 missing_authorization / invalid_api_key, 403 plan_required, 429 quota_exceeded, 502 provider_failed

Lista modeli

GET /v1/models

Zwraca modele czatu, obrazu i wideo z krótkimi opisami. Użyj id jako *ResultModel lub modelId.

Dostępne w: Growth i Business

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.

Parametry zapytania

kind string opcjonalne: Opcjonalny filtr: chat, image lub video.

Przykładowe żądanie

curl https://api.yourdomain.com/v1/models?kind=chat \
  -H "Authorization: Bearer pc_cloud_..."

Odpowiedź sukcesu

{
  "models": [
    {
      "id": "gpt-5.6-luna",
      "displayName": "GPT-5.6 Luna",
      "provider": "openai",
      "kind": "chat",
      "description": "Chat model",
      "targetModel": "gpt"
    }
  ]
}

Błędy

401 missing_authorization / invalid_api_key, 403 plan_required, 502 internal_error

Generuj obrazy

POST /v1/images

Generuje obrazy synchronicznie i zwraca podpisane URL-e. Growth: 80 obrazów na okres; Business: 300.

Dostępne w: Growth i Business

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.
Content-Type string wymagane: Dla ciał JSON musi być application/json.

Parametry ciała

prompt string wymagane: Prompt generowania. Nie może być pusty.
modelId string wymagane: Identyfikator modelu z GET /v1/models dla danego rodzaju.
aspectRatio string opcjonalne: Opcjonalne proporcje, np. 1:1, 16:9, 9:16 lub 4:3.
count integer opcjonalne: Opcjonalna liczba obrazów (1–4), jeśli model na to pozwala.
quality string opcjonalne: Opcjonalna jakość obrazu OpenAI: standard lub high.

Przykładowe żądanie

curl -X POST https://api.yourdomain.com/v1/images \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A red balloon over a lake at dusk","modelId":"gpt-image-2","aspectRatio":"16:9"}'

Odpowiedź sukcesu

{
  "jobId": "11111111-1111-1111-1111-111111111111",
  "status": "completed",
  "kind": "image",
  "modelId": "gpt-image-2",
  "results": [
    {
      "storagePath": "user/job-0.png",
      "signedUrl": "https://...",
      "mimeType": "image/png"
    }
  ]
}

Błędy

400 prompt_required / model_not_allowed, 401 missing_authorization, 403 plan_required, 429 quota_exceeded, 502 provider_failed

Generuj wideo

POST /v1/videos

Uruchamia zadanie wideo i zwraca HTTP 202 z jobId. Odpytuj GET /v1/videos/{jobId}. Growth: 20 wideo; Business: 50.

Dostępne w: Growth i Business

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.
Content-Type string wymagane: Dla ciał JSON musi być application/json.

Parametry ciała

prompt string wymagane: Prompt generowania. Nie może być pusty.
modelId string wymagane: Identyfikator modelu z GET /v1/models dla danego rodzaju.
aspectRatio string opcjonalne: Opcjonalne proporcje, np. 1:1, 16:9, 9:16 lub 4:3.
durationSeconds integer opcjonalne: Opcjonalny czas wideo w sekundach (zwykle 4 lub 8).

Przykładowe żądanie

curl -X POST https://api.yourdomain.com/v1/videos \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A red balloon drifting over a lake","modelId":"sora-2","aspectRatio":"16:9","durationSeconds":8}'

Odpowiedź sukcesu

{
  "jobId": "22222222-2222-2222-2222-222222222222",
  "status": "processing",
  "kind": "video",
  "modelId": "sora-2"
}

Błędy

400 prompt_required / model_not_allowed, 401 missing_authorization, 403 plan_required, 429 quota_exceeded, 502 provider_failed

Sprawdź zadanie wideo

GET /v1/videos/{jobId}

Zwraca status zadania wideo właściciela klucza. Ukończone zadania zawierają podpisane URL-e.

Dostępne w: Growth i Business

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.

Parametry ścieżki

jobId uuid wymagane: Identyfikator zadania zwrócony przez POST /v1/videos.

Przykładowe żądanie

curl https://api.yourdomain.com/v1/videos/22222222-2222-2222-2222-222222222222 \
  -H "Authorization: Bearer pc_cloud_..."

Odpowiedź sukcesu

{
  "jobId": "22222222-2222-2222-2222-222222222222",
  "status": "completed",
  "kind": "video",
  "modelId": "sora-2",
  "results": [
    {
      "storagePath": "user/job.mp4",
      "signedUrl": "https://...",
      "mimeType": "video/mp4"
    }
  ]
}

Błędy

400 job_id_required, 401 missing_authorization, 403 plan_required, 404 job_not_found

Pobierz użycie

GET /v1/usage

Zwraca użycie konwersji i mediów w bieżącym okresie Cloud wraz z limitami.

Dostępne w: Wszystkie plany Cloud

Nagłówki

Authorization string opcjonalne: Klucz API Cloud Bearer pc_cloud_…. Wymagany, jeśli nie wysłano X-Api-Key.
X-Api-Key string opcjonalne: Klucz API Cloud pc_cloud_…. Alternatywa dla Authorization.

Przykładowe żądanie

curl https://api.yourdomain.com/v1/usage \
  -H "Authorization: Bearer pc_cloud_..."

Odpowiedź sukcesu

{
  "used": 42,
  "limit": 5000,
  "planName": "growth",
  "periodStart": "2026-07-01T00:00:00Z",
  "periodEnd": "2026-08-01T00:00:00Z",
  "imagesUsed": 3,
  "imagesLimit": 80,
  "videosUsed": 1,
  "videosLimit": 20
}

Błędy

401 missing_authorization / invalid_api_key, 502 internal_error

Kontrola stanu

GET /v1/health

Sonda żywotności. Nie wymaga klucza API.

Dostępne w: Publiczne (bez klucza API)

Przykładowe żądanie

curl https://api.yourdomain.com/v1/health

Odpowiedź sukcesu

{ "status": "ok" }

Błędy

—