Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Kutsu API:a cURL:lla

Oppitunti 8 / 14 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Yleinen työkalu API:en testaamiseen
  2. Ensimmäinen cURL-pyyntösi
  3. Käytä /v1/responses-päätepistettä
  4. Hyödyllisiä cURL-valitsimia
  5. Lue sisältö tiedostosta
  6. Yleisten virheiden vianetsintä
  7. Keskeiset asiat

Yleinen työkalu API:en testaamiseen

cURL on komentorivityökalu, joka on saatavilla kaikissa käyttöjärjestelmissä. Sen avulla voit lähettää HTTP-pyyntöjä asentamatta SDK:ta tai kirjoittamatta erillistä ohjelmaa. Se on ihanteellinen työkalu päätepisteen nopeaan testaamiseen, pyynnön vianetsintään tai kutsujen automatisointiin shell-skriptissä.

Ensimmäinen cURL-pyyntösi

Näin lähetät pyynnön Grok API:lle cURL:lla:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [
      {"role": "user", "content": "Hello, introduce yourself in one sentence."}
    ]
  }'

Komennon purkaminen

  • curl https://api.x.ai/v1/chat/completions: lähettää POST-pyynnön (oletus -d:n ansiosta) päätepisteeseen
  • -H "Authorization: Bearer $XAI_API_KEY": lisää tunnistautumisotsikon avaimellasi
  • -H "Content-Type: application/json": määrittää, että sisältö on JSON-muodossa
  • -d '{...}': pyynnön sisältö JSON-muodossa

Käytä /v1/responses-päätepistettä

Nykyaikainen /v1/responses-päätepiste tarjoaa tiiviimmän syntaksin:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Explain machine learning to me in simple terms."
  }'

Huomaa, että input korvaa messages-kentän yksinkertaisissa pyynnöissä. Voit syöttää merkkijonon suoraan viestitaulukon sijaan.

Hyödyllisiä cURL-valitsimia

Muotoile JSON-tuloste

Raaka vastaus on vaikealukuinen. Käytä jq:ta sen muotoiluun:

curl -s https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}' | jq .

Valitsin -s (silent) piilottaa cURL:n edistymispalkin.

Poimi vain vastaus

Jos haluat saada vastauksen tekstin ilman metatietoja:

curl -s https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }' | jq -r '.choices[0].message.content'

Tarkastele vastausotsikoita

Jos haluat etsiä vikojä nopeusrajoituksissa tai virheissä, lisää -i näyttääksesi HTTP-otsikot:

curl -i https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Test"}'

Lue sisältö tiedostosta

Monimutkaisissa pyynnöissä on kätevää tallentaa JSON erilliseen tiedostoon:

# request.json
{
  "model": "grok-4.5",
  "messages": [
    {"role": "system", "content": "You are a translator."},
    {"role": "user", "content": "Translate into French: Hello world"}
  ],
  "temperature": 0.3
}

Viittaa siihen sitten merkinnällä @:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Yleisten virheiden vianetsintä

  • 401 Unauthorized: virheellinen tai puuttuva API-avain. Tarkista komennolla echo $XAI_API_KEY
  • 400 Bad Request: väärin muotoiltu JSON. Validoi JSON komennolla jq . < request.json
  • 429 Too Many Requests: olet ylittänyt nopeusrajoituksen. Odota muutama sekunti
  • 404 Not Found: tarkista URL-osoite ja päätepisteen polku

Keskeiset asiat

  • cURL sopii erinomaisesti testaamiseen ja vianetsintään ilman koodin kirjoittamista
  • Tunnistaudu käyttämällä -H "Authorization: Bearer $XAI_API_KEY"
  • Käytä jq:ta JSON-vastausten muotoiluun ja suodattamiseen
  • Tallenna monimutkaiset pyynnöt erillisiin JSON-tiedostoihin