OpenAI API

Mis on OpenAI API ja millal seda kasutada?

OpenAI API on majutatud arendajaplatvorm. Rakendus saadab HTTPS-päringu, mis sisaldab mudelit, juhiseid ja sisendit; OpenAI töötleb päringu ning tagastab genereeritud väljundi või muud vastuselemendid. Seejärel saab rakendus tulemust kuvada, salvestada või kasutada seda täiendava koodi käivitamiseks.

Uute otse mudeliga integreerimiste soovitatav lähtekoht on Responses API aadressil POST /v1/responses. See toetab nii tavalist teksti genereerimist kui ka voogedastust, pildi- ja failisisendeid, majutatud tööriistu, kohandatud funktsioonikutseid, struktureeritud väljundeid ja vestluse jätkamist. Chat Completions on ühilduvate olemasolevate integratsioonide jaoks endiselt saadaval, kuid uued rakendused peaksid üldjuhul alustama Responses API-st.

API on mõeldud serveripoolsetele rakendustele, taustsüsteemidele, automatiseerimissüsteemidele, otsingu- ja andmeotsingulahendustele, klienditoe tööriistadele, dokumenditöötluse töövoogudele ning agentsetele rakendustele. See sobib vähem olukordadesse, kus vajate täielikult võrguühenduseta töötavat mudelit, kindlat taristut ilma sõltuvuseta majutatud teenusest või kulu, mis ei tohi kasutuse mahust sõltuda.

Kellele see on mõeldud?

See sobib nii algajale, kes ehitab väikest serveri lõpp-punkti, kui ka kesktaseme arendajale, kes rakendab tööriistu, dokumenditöötlust, olekuga vestlusi või agentide orkestreerimist. Lihtsad päringud vajavad ainult API-võtit, saadaolevat mudelit ning SDK-d või HTTPS-klienti. Keerukamad rakendused peavad arvestama ka tööriistade käivitamise, korduskatsete, päringulimiitide, privaatsusseadete, vastuste salvestamise ja mudelipõhise hinnastamisega.

Kuidas API-le juurdepääs saada?

1. Looge OpenAI arendajaplatvormil konto ja projekt.
2. Looge platvormi võtmehaldusvahendite abil API-võti.
3. Salvestage võti serveripoolsesse keskkonnamuutujasse, näiteks OPENAI_API_KEY.
4. Installige ametlik SDK või saatke HTTPS-päringuid API baas-URL-ile.
5. Jälgige algusest peale kasutust, arveldust, vigu, päringute ID-sid ja päringulimiitide päiseid.

Standardne baas-URL on https://api.openai.com/v1. Päringud autentitakse kandjapääsuloaga päises Authorization. Ärge kunagi paigutage API-võtit brauseri JavaScripti, mobiilirakendusse, avalikku koodihoidlasse ega muusse kliendipoolsesse paketti. Turvalisem lahendus on saata päringud oma serverist, nii jääb mandaat kasutaja seadmest välja.

Töölaud ja Playground

Arendaja töölaud pakub API-võtmete haldust, projekte, kasutuse jälgimist, arveldusseadeid, Chat Playgroundi, Agent Builderit ja seotud arendustööriistu. Playground kasutab sama API-taristut, seega lähevad selle päringud API kasutuse ja hinnastamise alla. See on kasulik viipade ja konfiguratsioonide testimiseks enne päringu rakenduse koodi viimist.

Millise API ja mudeli peaks valima?

Uue otse mudelile saadetava päringu puhul alustage Responses API-st. Valige ülesande, vajaliku modaalsuse, latentsuse, väljundikvaliteedi, konteksti vajaduste ja eelarve põhjal praegu saadaolev mudel. Mudelite saadavus ja täpne hinnastamine võivad muutuda, seega kontrollige valitud mudelit enne juurutamist kehtivast mudelite ja hinnastamise dokumentatsioonist.

Responses API on ühe mudelisuhtluse peamine liides. Kergekaaluliseks jätkamiseks edastage previous_response_id. Seansside, seadmete, tööprotsesside või tööde vahel jagatava püsiva oleku jaoks kasutage Conversations API-t. Tööriistu, üleandmisi, kaitsemeetmeid, seansse, jälgimist või liivakastikäitumist hõlmavate hallatud agentide töövoogude puhul kasutage aegunud Assistants API asemel Agents SDK-d või praeguseid Agents API-sid.

Esimese päringu tegemine

Installige ametlik Python SDK käsuga pip install openai, määrake serverikeskkonnas OPENAI_API_KEY ja tehke Responses API päring. Allolev mudelinimi on näide esitatud praeguse platvormiteabe põhjal; kontrollige enne näite käivitamist, et see oleks teie kontol saadaval.

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.responses.create(
    model="gpt-6-astra",
    instructions="You are a concise technical assistant.",
    input="Explain idempotent API retries in two sentences."
)

print(response.output_text)

Sama toimingu saab saata otse HTTPS-i kaudu:

curl -sS https://api.openai.com/v1/responses 
  -H "Authorization: Bearer $OPENAI_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "gpt-6-astra",
    "instructions": "You are a concise technical assistant.",
    "input": "Explain idempotent API retries in two sentences."
  }'

Tootmiskeskkonnas kontrollige HTTP olekut, käsitlege struktureeritud API-vigu, logige päringu ID ning vältige täieliku vastuse või tundliku sisendi logidesse lisamist, välja arvatud juhul, kui teie andmekäitluspoliitika seda lubab.

Kuidas vastust mõista?

Responses API tulemus ei piirdu ühe lihtsa tekstijadaga. See võib sisaldada väljundelemente, näiteks sõnumeid, arutlusega seotud elemente, tööriistakutseid ja tööriistade tulemusi. Ametlik SDK pakub mugavat viisi genereeritud teksti eraldamiseks, kui tekst on olemas: response.output_text.

Kui vastus nõuab funktsioonikutset, käivitab funktsiooni teie rakendus, mitte mudel. Teie kood loeb funktsiooni nime ja argumendid, valideerib need, sooritab toimingu ning saadab tulemuse koos seotud kutse identifikaatoriga tagasi. Seejärel saab mudel koostada kasutajale mõeldud lõpliku vastuse. Ärge käsitlege mudeli genereeritud argumente automaatselt usaldusväärse sisendina; valideerige rakenduse koodis õigused, tüübid, vahemikud ja soovitud toiming.

Vestluse jätkamine

Kergekaaluliseks serveri hallatavaks jätkamiseks edastage varasema vastuse identifikaator järgmiselt: previous_response_id:

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=response.id,
    input="Now rewrite those tips as a checklist."
)

print(second.output_text)

Vastuseid säilitatakse vaikimisi 30 päeva, kui salvestamist ei ole keelatud. Vestlusobjektidel ja nende elementidel on eraldi püsivuskäitumine, seega valige olekumehhanism teadlikult, kui andmed peavad säilima kauem või olema jagatud rakenduse komponentide vahel.

Kuidas OpenAI API hinnastamine toimib?

OpenAI API hinnastamine põhineb peamiselt kasutusel, mitte ühel fikseeritud kuutasuga API-tellimusel. Mudeli järeldamine maksustatakse üldjuhul sisendtokenite, asjakohasel juhul vahemällu salvestatud sisendtokenite ja väljundtokenite alusel. Heli, pildid, video, reaalaja seansid ja muud modaalsused võivad kasutada erinevaid arvestusühikuid.

Majutatud võimalustega võivad kaasneda eraldi tasud. Näiteks veebotsingu päringud, failotsingu salvestus ja tööriistakutsed, majutatud konteinerid või kooditõlgenduse seansid, piltide genereerimine, video genereerimine ja reaalajaheli. Batch-, Flex-, Fast-, piirkondliku töötlemise, Scale Tieri ja Reserved Tieri valikud võivad hinda või jõudlusnäitajaid muuta.

Kõigi mudelite ja funktsioonide jaoks ei ole ühtset päringu hinda. Hinnastamine muutub sageli ning enne kulude modelleerimist või hankimist tuleks kontrollida ametlikku ajakohast hinnalehte. Jälgige rakenduses nii sisendi kui ka väljundi kasutust ning pidage meeles, et korduskatsed, pikk vestlusajalugu, tööriistakutsed, failitöötlus ja multimodaalsed sisendid võivad kogutarbimist suurendada.

API kaudu saadaolevad võimalused

Väljundi voogedastus

Voogedastus kasutab serveri saadetud sündmusi, et edastada väljundit järk-järgult. See vähendab tajutavat latentsust, sest rakendus saab osalist väljundit kuvada enne täieliku vastuse valmimist. SDK väljastab muu hulgas sündmusi, näiteks response.output_text.delta, tekstifragmentide jaoks.

stream = client.responses.create(
    model="gpt-6-astra",
    input="Explain server-sent events briefly.",
    stream=True
)

for event in stream:
    if getattr(event, "type", "") == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()

Voogedastus ei kaota vajadust käsitleda vigu ega mittetäielikku väljundit. Kasutajaliides peab arvestama ühenduse katkemise, tühistamise, modereerimise või eeskirjade rakendamisega ning võimalusega, et vastus sisaldab mittetekstilisi sündmusi.

Funktsiooni- ja tööriistakutsed

Funktsioonikutsed võimaldavad mudelil taotleda teie rakenduse kirjeldatud toimingut, näiteks tellimuse otsimist või tarnehinna arvutamist. Teie server määratleb funktsiooni skeemi, võtab kutse vastu, käivitab usaldusväärse rakenduse koodi ja saadab tulemuse. Mudel ei saa sellega otsest juurdepääsu teie andmebaasile ega ärisüsteemidele.

OpenAI pakub ka majutatud tööriistu, sealhulgas veebiotsingut, failotsingut, kooditõlgendust, piltide genereerimist, arvuti kasutamisega seotud võimalusi, kaug-MCP-d, shelli ja tööriistaotsingut. Saadavus sõltub mudelist, lõpp-punktist, kontost ja tööriistapõhistest piirangutest. Käsitlege tööriistu eraldi kulude, turvalisuse ja töökindluse piiridena.

Structured Outputs

Structured Outputs piirab toetatud mudelite ja skeemide puhul vastuse esitatud JSON Schema järgimiseks. Responses API-s seadistage teksti vorming range skeemiga:

schema = {
    "type": "object",
    "properties": {
        "answer": {"type": "string"},
        "confidence": {"type": "number"}
    },
    "required": ["answer", "confidence"],
    "additionalProperties": False
}

structured = client.responses.create(
    model="gpt-6-astra",
    input="State whether HTTPS encrypts data in transit.",
    text={
        "format": {
            "type": "json_schema",
            "name": "answer",
            "strict": True,
            "schema": schema
        }
    }
)

print(structured.output_text)

Structured Outputs erineb varasemast JSON-režiimist. JSON-režiimi eesmärk on luua korrektne JSON, Structured Outputs on aga mõeldud esitatud skeemi jõustamiseks JSON Schema toetatud alamhulgas. Rakendus peab siiski tagastatud andmeid valideerima ning käsitlema keeldumist, kärpimist ja transpordivigu.

Failid, pildid ja multimodaalne sisend

Ühilduvad mudelid võivad vastu võtta piltide URL-e, üleslaaditud pilte, failide identifikaatoreid ja dokumendisisendeid. Files API toetab failide üleslaadimist, hankimist, allalaadimist, kustutamist, aegumispoliitikate määramist ja eri otstarbeks mõeldud failide käsitlemist. Faile saab kasutada ka failotsingus, pakettöötluses, hindamistes ja muudes töövoogudes.

Piltide ja failide töötlemisega kaasnevad täiendavad privaatsuse, turvalisuse, saadavuse ja hinnastamise kaalutlused. Veenduge, et valitud mudel ja lõpp-punkt toetaksid vajalikku sisendit, ning vältige tundliku materjali üleslaadimist, kui säilitus- ja lepingulised nõuded ei ole täidetud.

Agendid, heli ja reaalajar rakendused

Laiem platvorm sisaldab reaalajas suhtluse, heli, piltide genereerimise, video genereerimise, manuste, modereerimise, failide, pakettide, hindamiste ja agentide töövoogude API-sid ning tööriistu. Agents SDK lisab orkestreerimisfunktsioonid, näiteks tööriistad, üleandmised, agentidena kasutatavad tööriistad, kaitsemeetmed, seansid, jälgimise, voogedastusega käitused, hääleagendid, reaalajaagendid ja liivakastiagendid. OpenAI mudelite kutsumiseks kasutab see vaikimisi Responses API-t, pakkudes samal ajal kõrgema taseme käituskeskkonda.

SDK-d ja toetatud programmeerimiskeeled

Ametlikud SDK-d ja teegid on saadaval Pythonile, JavaScriptile ja TypeScriptile, Go-le, Javale, .NET-ile ja Rubyle. Ametlikud Pythoni ja JavaScripti SDK-d pakuvad Responses API-le otsest ligipääsu. PHP-rakendused saavad kasutada REST API-t cURL-i või muu HTTP-kliendi kaudu; teenusepakkuja spetsiifiline PHP SDK ei ole vajalik.

Kasutage järjepidevalt üht praegust SDK versioonipõlvkonda. Hoidke SDK versioonid kontrolli all, testige mudelite ja funktsioonide saadavust tootmisevälises projektis ning tutvuge praeguse API viitega, kui päring kasutab tööriistu, struktureeritud väljundeid, voogedastust, faile või olekut.

Täiustatud näide: funktsiooni deklareerimine

Järgnev JavaScripti muster deklareerib funktsiooni. See näitab deklaratsiooni etappi; tootmiskood peab kontrollima tagastatud funktsioonikutsete elemente, valideerima argumendid, käivitama funktsiooni ja saatma tulemuse järelpäringuga.

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "What is the weather in Paris?",
  tools: [{
    type: "function",
    name: "get_weather",
    description: "Get the current weather for a city.",
    parameters: {
      type: "object",
      properties: { city: { type: "string" } },
      required: ["city"],
      additionalProperties: false
    },
    strict: true
  }]
});

console.log(response.output);

Päris rakenduses peaks funktsioon kutsuma heakskiidetud ilmateenust, jõustama autoriseerimise ja sisendi valideerimise ning tagastama piiratud tulemuse. Ärge lubage mudelil valida suvalisi URL-e, shellikäske, andmebaasipäringuid ega õigustega toiminguid ilma selgesõnalise turvakihita.

Piirangud ja tootmiskeskkonna kaalutlused

Päringulimiidid, korduskatsed ja latentsus

Piirangud sõltuvad organisatsioonist, projektist, mudelist, lõpp-punktist, kasutustasemest ja töötlemisrežiimist. Responses API vastused sisaldavad päringu- ja tokenipäiseid, näiteks x-ratelimit-limit-requests, x-ratelimit-remaining-requests ja x-ratelimit-reset-requests, koos nende tokenipõhiste vastetega.

Tootmiskliendid peaksid neid päiseid kontrollima, järgima võimaluse korral edastatud väärtust retry-after, kasutama korduskatseteks piiratud eksponentsiaalset tagasiviivitust ning logima päringute ID-d. Korduskatsed tuleb hoolikalt kavandada: kirjutuskaitstud genereerimise kordamine võib olla sobiv, kuid kliendilt tasu võtva või olekut muutva tööriistakutse kordamine võib tekitada topeltmõjusid. Vajaduse korral kasutage oma rakenduses idempotentsuse kontrolli.

Latentsus sõltub mudelist, viiba ja väljundi suurusest, arutluse intensiivsusest, tööriistade kasutamisest, järjekorrast, võrgutingimustest ja töötlemistasemest. Voogedastus parandab esimese nähtava väljundini jõudmise aega, kuid ei pruugi vähendada genereerimise koguaega. Fast- ja ettevõtetele mõeldud mahutavusvalikud võivad sobilike kontode jõudlust parandada.

Privaatsus ja andmete säilitamine

OpenAI sõnul ei kasutata API andmeid vaikimisi mudelite treenimiseks ega täiustamiseks, välja arvatud juhul, kui klient sellega sõnaselgelt nõustub. Kuritarvituste jälgimise logisid säilitatakse vaikimisi üldjuhul kuni 30 päeva. Responses API vastuseid säilitatakse vaikimisi 30 päeva ning neid saab luua salvestamiseta; failidel ja vestlustel on oma püsivuskäitumine.

Nõuetele vastavad organisatsioonid võivad taotleda selliseid kontrolle nagu Zero Data Retention või Modified Abuse Monitoring, kuid kehtivad lõpp-punkti, funktsiooni, geograafilised ja lepingulised piirangud. Piltide ja failide sisendeid võidakse töödelda spetsiaalse turvakontrolli abil. Enne isikuandmete, konfidentsiaalse, reguleeritud või kliendile kuuluva teabe saatmist tutvuge kohaldatavate andmekontrollidega.

Pärandfunktsioonid ja saadavuse erandid

Pärandfunktsioon Assistants API ei ole mõeldud uute integratsioonide jaoks. Soovitatavad üleminekuteed on Responses API, Conversations API, Agents SDK või praegused Agents API-d. Peenhäälestus on sobilikele olemasolevatele kasutajatele endiselt dokumenteeritud, kuid praegune hinnastamisteave kirjeldab peenhäälestusplatvormi sulgemist ja seda, et uued kasutajad sellele enam ligi ei pääse. Ärge muutke uut projekti peenhäälestusest sõltuvaks, ilma et oleksite konto sobivust kinnitanud.

Üksikutel mudelitel, tööriistadel, piirkondadel, modaalsustel, töötlemistasemetel ja skeemidel võivad olla eraldi piirangud. Kontrollige saadavust ja täpset käitumist kehtivast dokumentatsioonist, mitte ärge eeldage, et iga võimalus töötab iga mudeliga.

Millal on OpenAI API hea või halb valik?

See on hea valik, kui:

• Soovite majutatud API-t ametlike SDK-de ja ühtse ajakohase liidesega.
• Rakendus vajab teksti kõrval pildi-, faili-, heli-, otsingu- või tööriistafunktsioone.
• Soovite voogedastust, funktsioonikutseid, struktureeritud JSON-väljundit või hallatud vestlusolekut.
• Eelistate kasutuspõhist arveldamist ega soovi mudelitaristut ise hallata.
• Vajate võimalust liikuda lihtsast mudelipäringust tööriistade või agentide orkestreerimiseni.

See võib olla halb valik, kui:

• Rakendus peab töötama täielikult võrguühenduseta või taristus, mis ei saa välise teenusega ühendust võtta.
• Muutuv kasutuspõhine kulu on vastuvõetamatu või raskesti jälgitav.
• Nõuded sõltuvad mudelist, tööriistast, piirkonnast, säilituspoliitikast või peenhäälestuse töövoost, mida teie konto ei toeta.
• Süsteem ei talu võrgu latentsust, teenusekatkestusi, mudelite muutuva saadavuse ega lõpp-punktide arenguga kaasnevaid muutusi.
• Te ei saa töödeldava teabe jaoks kehtestada vastuvõetavat privaatsus- ja andmete säilitamise korda.

Esimese rakenduse puhul alustage ühe serveripoolse Responses API päringuga, lisage kasutuse ja vigade logimine ning võtke voogedastus, struktureeritud väljundid, failid, tööriistad või Agents SDK orkestreerimine kasutusele alles siis, kui rakendus neid vajab. Nii jääb esialgne integratsioon arusaadavaks, kuid alles jääb võimalus täiustatud töövoogudeks.