Mis on Z.ai API?
Z.ai API on arendajatele mõeldud platvorm, mille kaudu saab tarkvarast kutsuda GLM-mudeleid ja nendega seotud teenuseid. Selle peamine liides on OpenAI-ga ühilduv vestluse lõpetamise API, mis toetab tavalisi vastuseid, serverilt saadetavate sündmuste voogedastust, funktsioonikutseid, struktureeritud väljundit ja multimodaalset sõnumisisu.
Platvorm dokumenteerib ka spetsiaalseid API-sid piltide genereerimiseks, asünkroonseks videote genereerimiseks, heli transkribeerimiseks, OCR-i ja paigutuse analüüsiks, veebiotsinguks, veebi sisu lugemiseks, tokeniseerimiseks, tõlkimiseks ja agentide töövoogudeks. Need võimalused ei pruugi olla saadaval iga mudeli või lõpp-punkti kaudu, seega peaks rakendus kontrollima dokumentatsioonist täpselt selle toimingu tingimusi, mida kavatsetakse kasutada.
Z.ai sobib hästi siis, kui rakendus vajab GLM-mudeleid, pika kontekstiga või arutlusele keskenduvaid töökoormusi, kodeerimisabi, multimodaalset sisendit, väliseid tööriistu või OpenAI-ga ühilduvaid päringumustreid kasutavat teenusepakkujat. See võib sobida halvasti juhul, kui organisatsioon vajab kõigis piirkondades ühtlaselt kättesaadavat teenust, kõigi kontode jaoks ühtset ja selgelt dokumenteeritud andmete säilitamise poliitikat või küpset tarbijatele suunatud personaliseerimis- ja mobiiliökosüsteemi.
Juurdepääsu saamine ja API-võtme loomine
Alustage Z.ai arendaja- või mudeli-API platvormilt ning looge konto või logige sisse. API-võtmed luuakse või saadakse Z.ai API portaalist. Hoidke võtit serveri poolel ja laadige see keskkonnamuutujast, mitte brauserikoodist, lähtekoodihoidlast, logidest või kasutajale nähtavast konfiguratsioonist.
Üldine API kasutab baasaadressi https://api.z.ai/api/paas/v4. Kodeerimisplaani kliendid kasutavad eraldi baasaadressi https://api.z.ai/api/coding/paas/v4. Neid lõpp-punkte ei tohiks segamini kasutada: kodeerimise lõpp-punkt on mõeldud kodeerimisplaani juurdepääsuks, üldist lõpp-punkti kasutatakse tavaliste API ressursipakettide ja ettemakstud saldode jaoks.
- Üldise API baasaadress:
https://api.z.ai/api/paas/v4 - Kodeerimisplaani baasaadress:
https://api.z.ai/api/coding/paas/v4 - Põhitoiming:
POST /chat/completions - Autentimine:
Authorization: Bearer YOUR_API_KEY - Päringu vorming: JSON üle HTTPS-i
API ja mudeli valimine
Esimese teksti genereerimise integratsiooni jaoks kasutage üldist vestluse lõpetamise lõpp-punkti ja valige oma kontol lubatud GLM-mudel. Praegune dokumentatsioon tõstab esile mudelit GLM-5.3 ja teisi seotud GLM-mudeleid, kuid saadaolev kataloog võib kontost, piirkonnast, paketist ja teenuse muudatustest sõltuvalt erineda. Kontrollige täpset mudelitunnust Z.ai ajakohasest dokumentatsioonist või kontoportaalist, mitte ärge eeldage, et kõik avaldatud mudelid on kõigile kasutajatele kättesaadavad.
Valige toiming vastavalt ülesandele. Vestluse lõpetamine on üldotstarbeline lähtekoht. Multimodaalne vestlus sobib siis, kui valitud mudel võtab vastu pilte või muud toetatud meediasisu. Veebiotsingul, veebi sisu lugemisel, OCR-il, piltidel, videol, helil, tõlkimisel ja agentide toimingutel on oma dokumentatsioon ning need võivad kasutada teistsugust päringu vormingut või asünkroonseid töövooge.
Kodeerimisplaani kasutamisel kasutage kodeerimise lõpp-punkti ja selle plaaniga seotud kvooti. Üldise ettemakstud API saldo ja kodeerimisplaani kvoodid on eraldi. See erinevus on oluline juhul, kui päring õnnestub ühe lõpp-punkti kaudu, kuid nurjub, sest kontol puudub teise jaoks vastav ressurss või õigus.
Esimese päringu tegemine
Järgmine päring saadab üldise vestluse lõpetamise lõpp-punkti lühikese vestluse. Enne käivitamist määrake shellis ZAI_API_KEY. Mudelinimi on praeguse dokumentatsiooni põhjal toodud näitena; vajaduse korral asendage see oma kontol lubatud mudeliga.
set -euo pipefail
: "${ZAI_API_KEY:?Set ZAI_API_KEY first}"
curl --fail-with-body --silent --show-error
--request POST
--url https://api.z.ai/api/paas/v4/chat/completions
--header "Authorization: Bearer ${ZAI_API_KEY}"
--header "Content-Type: application/json"
--data '{
"model": "glm-5.3",
"messages": [
{
"role": "system",
"content": "You are a concise technical assistant."
},
{
"role": "user",
"content": "Explain API rate limiting in three bullet points."
}
],
"temperature": 0.2
}'Päring sisaldab mudelitunnust ja järjestatud massiivi messages. Süsteemisõnumiga saab määrata üldise käitumise, kasutajasõnum sisaldab aga praegust ülesannet. Mitme vooruga vestluse korral salvestab rakendus asjakohase ajaloo ja saadab selle järgmise päringuga uuesti.
Vastuse mõistmine
Edukalt töödeldud voogedastuseta vastus järgib tuttavat vestluse lõpetamise mustrit. Genereeritud tekst loetakse tavaliselt esimese valiku sõnumi sisust:
response.choices[0].message.contentRakendused peaksid siiski kontrollima puuduvate valikute, tühja sisu, tööriistakutsete ja veavastuste olemasolu. Ärge eeldage, et iga edukas vastus sisaldab tavalist teksti: mudel võib tagastada tööriista kutsumise päringu või spetsiaalne toiming võib tagastada teistsuguse, dokumentatsioonis kirjeldatud struktuuri.
Tootmiskoodis parsige JSON-vastus, kontrollige HTTP olekut, salvestage päringu identifikaator, kui see on saadaval, ning käsitlege teenusepakkuja vigu nii, et API-võti ega tundlik päringu sisu ei satuks logidesse.
Kuidas Z.ai API hinnastamine toimib?
Üldise API kasutamine põhineb kasutusel, mitte ühel piiramatul tellimusel. Z.ai pakub tokenipakette ja ettemakstud API ressursse ning hind sõltub valitud mudelist ja konto tingimustest. Ettevõtte-, mahu- või ärikliendi hinnastamist võidakse korraldada müügiosakonna kaudu. Avalikud hinnad ja mudelite kättesaadavus võivad muutuda, seega kontrollige projekti eelarve hindamisel Z.ai praeguseid hinnalehti.
Kodeerimisplaanid on tavalisest API-arveldamisest eraldi. Neil on oma tellimuskvoodid ja kodeerimise lõpp-punkt. Kodeerimisplaani tellimust ei tohiks käsitleda üldotstarbelise saldona, mida saab kasutada kõigi API toimingute jaoks.
Eelarvestamisel mõõtke tüüpiliste päringute puhul nii sisendi kui ka väljundi kasutust, arvestage korduspäringute ja tööriistakutsetega ning käsitlege multimodaalseid või spetsiaalseid toiminguid eraldi, kui dokumentatsioon kasutab nende puhul teistsugust hinnastamist. Jälgige konto tarbimist ja kvooti, mitte ärge tuginege üksnes staatilisele hinnangule.
Voogedastus, vestlused ja multimodaalne sisend
Määrake stream väärtuseks true, et saada järk-järgult saabuvaid serverilt saadetavaid sündmusi. Voogedastus võimaldab liidesel kuvada teksti selle saabumise ajal, selle asemel et oodata kogu vastuse valmimist. Klient peaks töötlema delta-sisu, tuvastama lõpetava sündmuse ja käsitlema võimalikke veosisuga sündmusi.
Mitme vooruga rakendustes hoidke vestluse olekut oma rakenduses. Säilitage täpselt assistendi tööriistakutse sõnumid, tööriistakutsete identifikaatorid ja neile vastavad tööriistade tulemused. See on eriti oluline vestlustes, kus mudeli väljund vaheldub väliste toimingutega.
Vestluse lõpetamise API toetab multimodaalset sõnumisisu, sealhulgas teksti- ja pildisisendit; heli-, video- ja failisisendi kohta on olemas täiendav dokumentatsioon. Meedia tugi sõltub mudelist. Valige mudel, mis toetab sõnaselgelt vajalikku meediatüüpi, ja järgige dokumenteeritud sisuosade vormingut, selle asemel et eeldada, et kõik GLM-mudelid võtavad vastu igat tüüpi sisendit.
Funktsioonikutsed, tööriistad ja MCP
Funktsioonikutse võimaldab mudelil taotleda toimingut, mille rakendus ise teostab. Kirjeldate funktsiooni nime, selgituse ja JSON Schema laadse parameetrite määratlusega. Mudel ei käivita iseseisvalt turvaliselt suvalist koodi: rakendus peab argumendid valideerima, õigusi jõustama, funktsiooni käivitama ja saatma tulemuse järelpäringuga tagasi.
Tüüpiline töövoog on järgmine:
- Saatke kasutaja sõnum ja saadaolevate tööriistade määratlused.
- Kontrollige vastust tööriistakutse suhtes.
- Valideerige taotletud funktsioon ja selle argumendid.
- Käivitage ainult heakskiidetud toiming.
- Lisage assistendi tööriistakutse sõnum ja tööriista tulemus.
- Saatke uus lõpetamise päring, et mudel saaks koostada lõpliku vastuse.
Z.ai dokumenteerib ka MCP-serverite kutsumist. MCP saab ühendada mudeli väliste serveritega, kasutades dokumenteeritud transpordiviise, näiteks voogedastatavat HTTP-d või SSE-d. See võib toetada veebiotsingut, visuaalset analüüsi, dokumenditöötlust ja muid väliseid toiminguid, kuid kehtivad samad turvareeglid: piirake saadaolevaid tööriistu, valideerige sisendid, määrake ajalõpud ja käsitlege väliste tööriistade tulemusi ebausaldusväärsete andmetena.
Failid ja spetsiaalsed arendaja-API-d
Failide üleslaadimist kirjeldatakse agentide töövoogudes, sealhulgas viitematerjale kasutavates tõlketöövoogudes. Üldine multimodaalne vestlus võib valitud mudeli ja lõpp-punkti toel vastu võtta faililaadset sisu. Failitugi sõltub seega konkreetsest toimingust ega tähenda üldist lubadust, et mis tahes faili saab lisada mis tahes vestluspäringule.
Sõltuvalt kasutusjuhtumist saavad arendajad kasutada ka järgmisi API-sid:
- Piltide genereerimine
- Asünkroonne videote genereerimine
- Heli transkribeerimine
- OCR ja paigutuse analüüs
- Veebiotsing ja veebi sisu lugemine
- Tokeniseerimine ja tõlkimine
- Spetsiaalsed agentide vestlused, sealhulgas slaidi- ja tõlketöövood
Enne faili- või meediatöövoo rakendamist kontrollige, kas toiming on sünkroonne või asünkroonne, milline mudel või lõpp-punkt sisu vastu võtab, kuidas tulemusi hangitakse ning millised kontoõigused või kvoodid kehtivad.
Struktureeritud JSON-väljundi taotlemine
Ühilduvad mudelid ja päringurežiimid toetavad struktureeritud väljundi juhtelemente. JSON-objekti kujul vastust saab taotleda väärtusega response_format, kuid tagastatud tekst tuleks siiski parsida ja valideerida rakenduse enda skeemi alusel. Struktureeritud väljund ei kõrvalda vajadust käsitleda toetamata mudeleid, vigaseid vastuseid, puuduvaid välju ega kontopõhiseid piiranguid.
curl --fail-with-body --silent --show-error
--request POST
--url https://api.z.ai/api/paas/v4/chat/completions
--header "Authorization: Bearer ${ZAI_API_KEY}"
--header "Content-Type: application/json"
--data '{
"model": "glm-5.3",
"messages": [
{
"role": "user",
"content": "Return a JSON object with keys name and priority for a timeout bug."
}
],
"response_format": {"type": "json_object"}
}'Pärast vastuse saamist parsige sõnumi sisu JSON-ina ning valideerige tüüp ja nõutud väljad. Kui rakendus nõuab ranget skeemi, lükake vigased andmed tagasi või parandage need turvaliselt, selle asemel et edastada need otse äriloogikale.
Pythoni SDK ja integratsioonivõimalused
Z.ai dokumenteerib ametliku Pythoni SDK, mida levitatakse paketina zai-sdk, ning ametliku Java SDK. Järgmine Pythoni näide kasutab dokumenteeritud mustrit ZaiClient ning sisaldab tavalisi, voogedastatavaid ja struktureeritud väljundiga päringuid.
import json
import os
import sys
from zai import ZaiClient
api_key = os.environ.get("ZAI_API_KEY")
if not api_key:
raise SystemExit("Set ZAI_API_KEY before running this example")
client = ZaiClient(api_key=api_key)
try:
response = client.chat.completions.create(
model="glm-5.3",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Give me two practical API retry recommendations."},
],
temperature=0.2,
)
print(response.choices[0].message.content)
except Exception as exc:
print(f"Z.ai request failed: {exc}", file=sys.stderr)
raise
stream = client.chat.completions.create(
model="glm-5.3",
messages=[
{"role": "user", "content": "Explain server-sent events in four short steps."}
],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print()
structured = client.chat.completions.create(
model="glm-5.3",
messages=[
{"role": "user", "content": "Return JSON with keys title and severity for a
database timeout bug."}
],
response_format={"type": "json_object"},
)
print(json.loads(structured.choices[0].message.content))JavaScripti ja PHP rakendused saavad HTTP API-d otse kutsuda. Selle juhendi jaoks läbi vaadatud praegune dokumentatsioon kinnitab Pythoni ja Java SDK-de olemasolu, kuid dokumentatsiooniindeksist ei leidunud kinnitust ametliku JavaScripti või PHP SDK kohta.
Töölaud ja arendajatööriistad
Z.ai pakub mudeli-API lehte ja API portaali, kus saab katsetada juurdepääsu, mudeleid ja kasutust. Dokumentatsioon sisaldab kiirjuhendeid, HTTP-näiteid, SDK-juhendeid, API-viiteid, voogedastust, funktsioonikutsed, MCP-d, struktureeritud väljundit, veebiotsingut, agente ja spetsiaalseid meedia-API-sid.
Kasutage portaali või töölauda väikesteks käsitsi tehtavateks testideks, kuid korrake olulisi teste enne tootmiskasutust koodis. Töölaud võib kasutada mudelit, seadistust, kontoõigust või kvooti, mis erineb teie rakenduse kasutatavast keskkonnast.
Piirangud ja tootmiskasutuse kaalutlused
Z.ai avaldab eraldi kiiruspiirangute viite, kuid piirangud võivad mudeli, konto, paketi ja teenusejuurdepääsu järgi erineda. Kõigile klientidele sobivat ühtset universaalset piirangut ei tohiks kõvakodeerida. Rakendage ajutiste tõrgete korral piiratud korduskatseid eksponentsiaalse viivitusega, järgige HTTP veavastuseid ning jälgige kvooti ja kasutust.
Samuti ei ole iga mudeli või piirkonna kohta kontrollitud ühtki universaalset avalikku latentsusgarantiid. Latentsus sõltub mudeli valikust, viiba ja väljundi suurusest, arutlusseadetest, teenuse koormusest, võrgu teekonnast ja sellest, kas voogedastus on lubatud. Määrake rakendusele ajalõpud, vältige piiramatuid korduskatseid ja kujundage kasutajaliidesed nii, et need taluksid viivitusega või osalisi tulemusi.
Hoidke saladused viipadest ja lähtekoodist eemal. Minimeerige tundlikke andmeid, rakendage oma süsteemides säilitamise juhtelemente ning vaadake enne konfidentsiaalse või reguleeritud teabe saatmist üle kehtivad API kasutustingimused ja andmetöötluse lisa. Läbi vaadatud avalikud materjalid ei kehtesta üht universaalset API andmete säilitamise perioodi ega lihtsat treeningkasutuse reeglit, mis kehtiks kõigile API klientidele ja piirkondadele.
Lõpuks võivad mudelite ja funktsioonide kättesaadavus muutuda. Kontrollige juurutamise ajal toetatud mudeleid, käsitlege toetamata funktsioonide vigu, testige pika konteksti ja tööriistade töövooge realistliku koormuse all ning hoidke teenusepakkujaspetsiifiline käitumine rakenduse liidese taga, kui teisaldatavus on oluline.
Eelised ja piirangud
Millal on API hea valik?
- OpenAI-ga ühilduvad vestluse lõpetamise mustrid võivad olemasolevalt integratsioonilt üleminekut kiirendada.
- Platvorm hõlmab teksti, arutlust, kodeerimist, multimodaalset mõistmist, tööriistu, otsingut, agente ja spetsiaalseid meediatoiminguid.
- Lisaks otse HTTP kaudu integreerimisele on saadaval ametlik Pythoni ja Java SDK dokumentatsioon.
- MCP ja funktsioonikutsed võimaldavad ühendada mudelid rakenduse teenuste ja väliste tööriistadega.
- Üldine API kasutab ettemakstud ressursse ja kasutuspõhiseid pakette, mis võib sobida kasutuspõhist ostmist eelistavatele meeskondadele.
Mida hoolikalt hinnata?
- Mudelite, funktsioonide, kvootide ja piirkondade kättesaadavus võib erineda.
- Üldise API ressursid ja kodeerimisplaani kvoodid kasutavad erinevaid lõpp-punkte ja arveldustingimusi.
- Faili-, heli-, video-, struktureeritud väljundi ja tööriistade funktsioonid sõltuvad konkreetsest mudelist või toimingust.
- Kiiruspiirangud ja latentsus sõltuvad kontost ja töökoormusest ning neid ei kata üks universaalne avalik garantii.
- API andmete säilitamise, kustutamise, logimise ja treeningus kasutamise tingimused tuleb konkreetse konto või lepingu puhul üle kontrollida.
Millal kasutada Z.ai API-d?
Valige Z.ai, kui vajate GLM-il põhinevaid teksti- või kodeerimisfunktsioone, multimodaalset analüüsi, väliseid tööriistu, veebiotsingut, agentide töövooge või spetsiaalseid pildi-, video-, heli-, OCR-i ja tõlketoiminguid. Selle OpenAI-ga ühilduv põhiliides on praktiline ka arendajatele, kes soovivad tavapärast vestluse lõpetamise integratsiooni.
Hinnake alternatiive hoolikalt, kui teie rakendus sõltub ühtlasest kättesaadavusest kõigis piirkondades, väga küpsest mobiili- või tarbijaassistendi ökosüsteemist, ulatuslikest personaliseerimistööriistadest või täielikult läbipaistvatest ja kõigile kehtivatest andmete säilitamise ning treeningus kasutamise juhtelementidest. Kõigil juhtudel tehke tüüpilised testid täpselt selle mudeli, lõpp-punkti, konto, piirkonna, viiba suuruse ja tööriistade töövooga, mida tootmiskeskkonnas kasutama hakatakse.