Co to jest API? Wyjaśnienie na przykładzie AI i pierwszy curl

👁 115 przeczytań

API to umowa między dwoma programami: jeden wysyła zapytanie w ustalonym formacie, drugi odsyła odpowiedź, też w ustalonym formacie. Kiedy Twój skrypt pyta model AI o streszczenie maila, nie klika w okienko czatu, tylko wysyła przez internet paczkę tekstu w formacie JSON i dostaje JSON z powrotem. Ten tekst to pierwszy krok ścieżki API AI od zera, w której pokazuję wszystko na prawdziwych zapytaniach uruchomionych na moim komputerze.

API po ludzku: okienko z formularzem

Najprościej wyobrazić sobie API jako okienko w urzędzie, które przyjmuje tylko wypełnione formularze. Nie widzisz zaplecza, nie wiesz, kto i jak załatwia sprawę. Wiesz natomiast trzy rzeczy:

• do którego okienka podejść - to adres, czyli endpoint, np. https://openrouter.ai/api/v1/chat/completions;
• jak wypełnić formularz - to format zapytania opisany w dokumentacji: jakie pola są obowiązkowe, jakie opcjonalne;
• czym się wylegitymować - to klucz API, który dołączasz do każdego zapytania.

Urzędnik odsyła albo załatwioną sprawę, albo kartkę z kodem błędu: „brak podpisu”, „za dużo wniosków dzisiaj”, „system nie działa”. W API to są statusy HTTP, o których niżej.

Różnica między czatem a API jest taka, że czat (ChatGPT, Claude, Gemini) to gotowa aplikacja dla człowieka, a API to dostęp do tego samego modelu dla programu. Przez API model nie pamięta Twoich rozmów, nie ma przycisków ani historii. Za to możesz go wywołać tysiąc razy z arkusza, z bota albo z automatu, który chodzi w nocy. Płacisz wtedy nie abonament, tylko za zużyte tokeny, czyli kawałki tekstu - wyjaśniam je w tekście Tokeny AI: co to jest i ile kosztują.

Zapytanie i odpowiedź (request i response)

Każda rozmowa z API składa się z dwóch części. Zapytanie (request) zawiera:

1. Metodę - co chcesz zrobić. Do modeli AI prawie zawsze wysyłasz POST, bo przekazujesz treść.
2. Adres - endpoint konkretnej funkcji, np. generowanie tekstu albo lista modeli.
3. Nagłówki - metadane: klucz API (Authorization: Bearer ...) i typ treści (Content-Type: application/json).
4. Treść (body) - właściwe dane: który model, jakie wiadomości, jakie parametry.

Odpowiedź (response) ma kod statusu (np. 200, czyli wszystko dobrze) i treść, w której jest wygenerowany tekst oraz licznik zużytych tokenów. Tak wygląda prawdziwa odpowiedź, którą dostałem 4 października 2026 od modelu GPT-6 Luna przez OpenRouter (skróciłem ją do najważniejszych pól):

{
  "id": "gen-1791114764-uKPpeyAgJg4GJmOQhMp4",
  "object": "chat.completion",
  "model": "openai/gpt-6-luna",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Kraków zachwyca zabytkowym Rynkiem Głównym, klimatycznymi uliczkami i bogatą historią."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 36,
    "total_tokens": 52,
    "cost": 0.0000196
  }
}

Odczytuję ją tak: model odpowiedział zdaniem o Krakowie (content), skończył normalnie (finish_reason: stop), zużył 16 tokenów na wejściu i 36 na wyjściu, a całe zapytanie kosztowało 0,0000196 USD, czyli niecałe dwie tysięczne centa.

JSON w 2 minuty

JSON (JavaScript Object Notation) to tekstowy format zapisu danych, który czyta i człowiek, i każdy język programowania. Wystarczy znać pięć elementów:

• { } - obiekt, czyli zbiór par „klucz: wartość”, np. {"model": "openai/gpt-6-luna"};
• [ ] - lista, np. lista wiadomości w rozmowie;
• "tekst" - napis zawsze w podwójnym cudzysłowie (pojedynczy to błąd);
• liczby bez cudzysłowu: 0.7, 1024 - z kropką, nie z przecinkiem;
• true, false, null - prawda, fałsz, brak wartości.

Zapytanie do modelu AI to obiekt z polem model i listą messages. Każda wiadomość ma rolę (system - instrukcja dla modelu, user - Ty, assistant - wcześniejsze odpowiedzi modelu) i treść:

{
  "model": "openai/gpt-6-luna",
  "messages": [
    {"role": "user", "content": "Napisz jedno zdanie o Krakowie."}
  ]
}

Najczęstszy błąd początkujących to przecinek po ostatnim elemencie listy albo obiektu. JSON tego nie wybacza i serwer odpowie kodem 400. Gdy model ma zwracać JSON, a nie tylko go przyjmować, przyda się tryb opisany w tekście Structured output: jak zmusić AI do odpowiedzi w JSON.

Metody HTTP: GET, POST i reszta

W praktyce przez pierwsze tygodnie będziesz używać dwóch: GET do sprawdzania, co jest dostępne, i POST do generowania.

Statusy i błędy: 401, 429, 500 i inne

Kod statusu to trzycyfrowa liczba na początku odpowiedzi. Pierwsza cyfra mówi, czyja to wina: 2xx - sukces, 4xx - błąd po Twojej stronie, 5xx - błąd po stronie serwera.

Sprawdziłem, co naprawdę przychodzi, gdy zapomnę o kluczu. Zapytanie bez nagłówka Authorization do OpenRouter:

$ curl -s https://openrouter.ai/api/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"hej"}]}'
{"error":{"message":"No cookie auth credentials found","code":401}}

A tak wyglądają dwa błędy złapane przez mój skrypt w Pythonie: zły klucz i nieistniejący model. Ciekawostka: OpenRouter przy nieznanym modelu zwraca 400, a nie 404, więc w kodzie nie zakładaj jednego numeru dla jednej sytuacji.

401: sprawdź klucz API (Error code: 401 - {'error': {'message': 'User not found.', 'code': 401}})

400: popraw zapytanie (Error code: 400 - {'error': {'message': 'openai/gpt-7-nie-istnieje is not a valid model ID', 'code': 400}})

Jak obsłużyć te kody w kodzie i automatycznie ponawiać zapytania po 429, pokazuję w tekście Pierwsze zapytanie do API AI w Pythonie.

Pierwszy curl: zapytanie z terminala

curl to program do wysyłania zapytań HTTP z wiersza poleceń. Jest wbudowany w Windows 10 i 11 (jako curl.exe), macOS i Linuksa, więc nic nie instalujesz. Na początek zapytanie GET, które nie wymaga klucza - lista modeli w OpenRouter:

{"data":[{"id":"inclusionai/ling-3.1-flash","canonical_slug":"inclusionai/ling-3.1-flash-20261002","hugging_face_id":null,"name":"inclusionAI: Ling 3.1 Flash","created":1790950024,"description":"Ling 3.1 Flash is a hybrid reasoning mixture-of-experts model from inclusionAI, with 25B active parameters out of 560B total.","context

Dostałem obiekt z listą data, w której 4 października było 466 modeli. Teraz POST, czyli prawdziwe pytanie do modelu. Najpierw potrzebujesz klucza (instrukcja dla czterech dostawców jest w tekście Klucz API: jak go zdobyć i jak go nie spalić). W Git Bash, na Linuksie i na Macu:

#!/usr/bin/env bash
# Pierwsze zapytanie przez curl (Git Bash, Linux, macOS). Wcześniej: export OPENROUTER_API_KEY=sk-or-v1-...
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "messages": [{"role": "user", "content": "Napisz jedno zdanie o Krakowie."}]
  }'

W PowerShellu cudzysłowy w JSON-ie sprawiają kłopoty, dlatego treść zapytania trzymam w pliku zapytanie.json (pokazany wyżej), a curl tylko go wysyła. Zwróć uwagę na curl.exe zamiast curl - w starszym PowerShellu samo curl to alias innego polecenia:

# Windows PowerShell: treść zapytania w pliku zapytanie.json (omija problemy z cudzysłowami)
# Wcześniej w tym samym oknie: $env:OPENROUTER_API_KEY = "sk-or-v1-..."
curl.exe -s https://openrouter.ai/api/v1/chat/completions `
  -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
  -H "Content-Type: application/json" `
  -d "@zapytanie.json"

Oba warianty uruchomiłem na Windows 11 (Git Bash z curl 8.22 i Windows PowerShell). Model odpowiedział w obu przypadkach jednym zdaniem o Krakowie, a każde zapytanie kosztowało około 0,00002 USD. Oba pliki są w paczce promptowy-api-starter.

Co dalej

1. Załóż konto i klucz: Klucz API w OpenAI, Anthropic, Google AI Studio i OpenRouter.
2. Napisz pierwszy skrypt: Pierwsze zapytanie do API AI w Pythonie.
3. Policz koszty: Tokeny AI i kalkulator kosztu.
4. Gdy API przestanie mieć tajemnice, przejdź do automatyzacji i agentów: Agenci AI od zera.

Najczęstsze pytania

Co to jest API w prostych słowach?

To sposób, w jaki jeden program zamawia coś u drugiego: wysyła zapytanie w ustalonym formacie i dostaje odpowiedź w ustalonym formacie. Nie musi wiedzieć, jak drugi program działa w środku.

Co oznacza skrót API?

Application Programming Interface, czyli interfejs programistyczny aplikacji. Interfejs, bo to „styk” między dwoma programami, tak jak ekran i przyciski są interfejsem dla człowieka.

Czy do korzystania z API trzeba umieć programować?

Do pierwszego zapytania nie: wystarczy curl i skopiowane polecenie. Do czegoś użytecznego przyda się podstawowy Python albo narzędzie do automatyzacji, takie jak n8n czy Zapier, które wysyłają zapytania za Ciebie.

Czym różni się API od ChatGPT?

ChatGPT to aplikacja z abonamentem, historią i interfejsem dla człowieka. API OpenAI to dostęp do modeli dla programów, rozliczany za tokeny, bez historii rozmów i bez okienka czatu. Abonament ChatGPT nie obejmuje API - to osobne konta i osobne płatności.

Co to jest REST API?

To najpopularniejszy styl budowania API: zasoby mają swoje adresy, operacje wybierasz metodą HTTP (GET, POST, DELETE), a dane przesyłasz najczęściej w JSON. API modeli AI są zbudowane w tym stylu.

Źródła i data sprawdzenia

Zapytania uruchomiłem 4 października 2026 na Windows 11 przez OpenRouter, łączny koszt przykładów z tego tekstu: poniżej 0,0001 USD.

• OpenRouter - Quickstart
• OpenRouter - kody błędów
• MDN - kody statusu HTTP
• json.org - opis formatu JSON po polsku
• Anthropic - błędy API (w tym 529)