how-tos

Guida alla GPT-6.2 API: prima richiesta in cURL e Python, Responses e Chat Completions

Poyo.ai Team
9 min read
Share:

Guida alla GPT-6.2 API: prima richiesta in cURL e Python

Questa guida alla GPT-6.2 API ti porta da una chiave API a una richiesta funzionante per gpt-6.2-sol o gpt-6.2-astra in cURL e con l'SDK di OpenAI per Python, sia sull'endpoint Responses sia su Chat Completions. Ogni body di richiesta segue lo schema pubblicato da PoYo e le note di migrazione a GPT-6.2 di OpenAI aggiornate al 18 novembre 2026. Puoi prima testare i prompt sulla pagina del modello GPT-6.2 Sol o sulla pagina del modello GPT-6.2 Astra.

Non conosci ancora i modelli? La panoramica della GPT-6.2 API ne descrive limiti e posizionamento.

Prima di iniziare

Crea una chiave nella dashboard di PoYo e tienila sul tuo server:

export POYO_API_KEY="your-poyo-key"
FormatoEndpointUsalo quando
ResponsesPOST https://api.poyo.ai/v1/responsesNuovo codice, function tool, input di immagini, reasoning effort
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsCodice Chat Completions esistente, messaggi di solo testo, nessun tool

Ogni richiesta invia Authorization: Bearer $POYO_API_KEY. Gli esempi usano gpt-6.2-sol; sostituiscilo con gpt-6.2-astra per Astra. La struttura delle richieste è identica.

Tre regole della guida GPT-6.2 di OpenAI valgono per tutti gli esempi qui sotto:

  1. Non inviare temperature o top_p. OpenAI dice di ometterli, insieme a logprobs e top_logprobs su Chat Completions e a top_logprobs su Responses. Gli schemi di PoYo elencano ancora temperature e top_p per i modelli precedenti.
  2. Non impostare il reasoning effort su none; l'API lo rifiuta.
  3. Metti le istruzioni stabili in un messaggio developer all'inizio di input. GPT-6.2 accoda le instructions di primo livello dopo input, il che le sposta fuori dal prefisso memorizzabile in cache.

Prima richiesta alla GPT-6.2 API con cURL

curl https://api.poyo.ai/v1/responses \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.2-sol",
    "input": [
      {"role": "developer", "content": "You are a code reviewer. Be specific and cite line numbers."},
      {"role": "user", "content": "Review this function for race conditions: ..."}
    ],
    "reasoning": {"effort": "medium"},
    "max_output_tokens": 8000,
    "store": false
  }'

model e input sono obbligatori. input è una semplice stringa oppure un array di elementi con role (developer, system, user, assistant) e content. Altri campi documentati usati in questa guida: reasoning, max_output_tokens, stream, store, tools, tool_choice, previous_response_id e metadata.

La risposta è un oggetto Responses restituito direttamente. Il testo si trova nei blocchi output[].content[] con type: "output_text"; lo stato della chiamata è in status; i conteggi sono in usage.input_tokens, usage.output_tokens e usage.total_tokens.

Python con l'SDK di OpenAI

Punta l'SDK su PoYo:

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])

resp = client.responses.create(
    model="gpt-6.2-sol",
    input=[
        {"role": "developer", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
    ],
    reasoning={"effort": "medium"},
    max_output_tokens=8000,
)

print(resp.output_text)
print(resp.status, resp.usage)

resp.output_text è l'helper dell'SDK che unisce tutti i blocchi output_text. Registra resp.usage a ogni chiamata; la sezione sui costi qui sotto lo utilizza.

Chat Completions per il codice esistente

Se il tuo codice usa già chat.completions.create, cambia il modello e rimuovi i campi di campionamento:

resp = client.chat.completions.create(
    model="gpt-6.2-sol",
    messages=[
        {"role": "system", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Explain the CAP theorem with one example per trade-off."},
    ],
    max_tokens=4000,
)
print(resp.choices[0].message.content, resp.choices[0].finish_reason)

La stessa richiesta in cURL:

curl https://api.poyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.2-sol",
    "messages": [{"role": "user", "content": "Explain vector databases in one sentence."}],
    "max_tokens": 1000
  }'

Lo schema Chat Completions di PoYo documenta model, messages (content come stringa; ruoli system, user, assistant), max_tokens, stream, stop, n e i campi di penalità. Non documenta tools, e OpenAI dice che il tool calling di GPT-6.2 richiede Responses, quindi gli agenti vanno su /v1/responses.

Impostare il reasoning effort tramite la GPT-6.2 API

OpenAI chiama il campo reasoning.effort in Responses e reasoning_effort in Chat Completions. Il riferimento Responses di PoYo documenta reasoning (esempio {"effort": "medium"}); il suo riferimento Chat Completions non elenca ancora reasoning_effort, quindi questa guida imposta l'effort solo su Responses.

SituazioneImpostazioneFonte
Nuova integrazionemediumOpenAI: "Parti da medium per una nuova integrazione."
In precedenza none o minimallowNota di migrazione a GPT-6.2 di OpenAI
Task lunghi o complessiUn livello più altoOpenAI: un effort più alto "può aiutarlo a portare a termine i controlli finali"
noneRifiutatoPagine dei modelli di OpenAI

La guida al ragionamento di OpenAI elenca low, medium, high, xhigh e max tra i valori possibili, ma precisa che dipendono dal modello. Le pagine dei modelli GPT-6.2 non elencano i valori accettati, quindi invia una richiesta di prova prima di fissare nel codice un livello superiore a medium. I token di ragionamento sono fatturati come output e rientrano in max_output_tokens; OpenAI li riporta in usage.output_tokens_details.reasoning_tokens.

Streaming delle risposte della GPT-6.2 API

Con "stream": true, PoYo restituisce text/event-stream. Ogni riga data: è un JSON il cui type indica l'evento; il testo arriva come response.output_text.delta e response.completed contiene l'oggetto finale con usage. PoYo non invia righe event: separate e lo stream termina con data: [DONE].

stream = client.responses.create(
    model="gpt-6.2-sol",
    input="Write a 100-word product introduction for a log search tool.",
    reasoning={"effort": "low"},
    max_output_tokens=2000,
    stream=True,
    store=False,
)

usage = None
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        usage = event.response.usage
    elif event.type == "response.failed":
        raise RuntimeError(event.response)
print("\n", usage)

Su Chat Completions, stream=True restituisce eventi chat.completion.chunk; il testo è in choices[0].delta.content e l'ultimo chunk contiene usage.

Input di immagini

GPT-6.2 accetta immagini insieme al testo. Su PoYo, inviale a Responses come blocchi input_image con un URL pubblico o un Data URI completo (data:image/png;base64,...). La documentazione di PoYo consiglia di mettere il testo prima delle immagini:

{
  "model": "gpt-6.2-sol",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "List every service in this architecture diagram that writes to the database."},
        {"type": "input_image", "image_url": "https://example.com/diagram.png"}
      ]
    }
  ],
  "max_output_tokens": 3000
}

Leggere l'usage e calcolare il costo di una richiesta

Prezzi PoYo per 1M di token: Sol $1.60 di input, $8 di output, $0.08 di lettura dalla cache, $2 di scrittura in cache; Astra $6.40, $32, $0.32, $8 (1 credito = $0.005).

La guida al caching di OpenAI riporta le letture dalla cache fatturate in usage.input_tokens_details.cached_tokens e le scritture in usage.input_tokens_details.cache_write_tokens. Lo schema di PoYo include input_tokens_details e output_tokens_details senza elencarne le chiavi, quindi leggile in modo difensivo:

PRICES = {  # PoYo USD per 1M tokens: input, output, cache read, cache write
    "gpt-6.2-sol":   (1.60, 8.00, 0.08, 2.00),
    "gpt-6.2-astra": (6.40, 32.00, 0.32, 8.00),
}

def estimate_cost_usd(model: str, usage) -> float:
    p_in, p_out, p_read, p_write = PRICES[model]
    details = getattr(usage, "input_tokens_details", None)
    cached = getattr(details, "cached_tokens", 0) or 0
    written = getattr(details, "cache_write_tokens", 0) or 0
    fresh = usage.input_tokens - cached - written
    return (fresh * p_in + cached * p_read + written * p_write
            + usage.output_tokens * p_out) / 1_000_000

Considera questo valore una stima e riconcilialo con il tuo log di utilizzo di PoYo. Tutti i prezzi qui sono tariffe per contesto breve. OpenAI applica tariffe più alte oltre i 272K token di input, quindi controlla la pagina del modello per qualsiasi richiesta di quelle dimensioni. Gli esempi calcolati sono in Prezzi della GPT-6.2 API.

Errori da gestire

HTTPCausaCosa fare
400Campo non valido (validation_error, con dettagli)Correggi il body; un effort none o un campo non documentato può finire qui
401Chiave API mancante o non validaControlla l'header Authorization
402Crediti insufficientiRicarica prima di riprovare
404Modello sconosciuto (model_not_found)Controlla l'ID: gpt-6.2-sol, gpt-6.2-astra
429Rate limit raggiuntoAttendi e riprova
500 / 502 / 503Errore del server o upstreamRiprova con backoff esponenziale

La documentazione di PoYo indica che al momento gli endpoint LLM non hanno rate limit, ma gestisci comunque il 429. Con l'SDK di OpenAI, intercetta openai.APIStatusError e distingui i casi in base a status_code. Riprova solo i 5xx e il 429; un 400 fallisce di nuovo finché il body non cambia. I body completi sono nei codici di errore di PoYo.

Checklist prima del rilascio

  • Tieni POYO_API_KEY lato server; non includerla mai nel codice browser o mobile.
  • Rimuovi temperature e top_p da ogni percorso di richiesta GPT-6.2, comprese le funzioni helper condivise.
  • Imposta sempre max_output_tokens (o max_tokens) e lascia spazio ai token di ragionamento entro quel limite.
  • Registra status / finish_reason e l'intero blocco usage accanto al tuo ID di richiesta, così le risposte troncate e i picchi di costo restano visibili.
  • Metti il contesto lungo e stabile nel primo messaggio developer e la domanda variabile per ultima, così il prompt caching ha la possibilità di applicarsi.
  • Fissa l'ID modello nella configurazione, così puoi passare da gpt-6.2-sol a gpt-6.2-astra senza un deploy.

Per tool, streaming delle chiamate ai tool e caching nelle sessioni lunghe degli agenti, prosegui con GPT-6.2 API per agenti di coding.

Domande frequenti

Come chiamo la GPT-6.2 API in Python?

Usa l'SDK di OpenAI con base_url="https://api.poyo.ai/v1", la tua chiave PoYo e model="gpt-6.2-sol" o "gpt-6.2-astra" in client.responses.create.

La GPT-6.2 API supporta lo streaming?

Sì, su entrambi gli endpoint. Imposta stream: true; Responses invia eventi tipizzati come response.output_text.delta e Chat Completions invia eventi chat.completion.chunk. Entrambi terminano con data: [DONE].

Come imposto il reasoning effort della GPT-6.2 API?

Invia "reasoning": {"effort": "medium"} su /v1/responses. OpenAI consiglia di partire da medium e rifiuta none.

Perché la mia richiesta alla GPT-6.2 API fallisce con temperature?

OpenAI dice di omettere temperature e top_p per GPT-6.2. Rimuovili e controlla la lunghezza dell'output con max_output_tokens o max_tokens.

Come invio un'immagine alla GPT-6.2 API?

Usa /v1/responses con un blocco input_image (URL o Data URI) dopo un blocco input_text. Lo schema Chat Completions di PoYo documenta solo contenuti di tipo stringa.

Share: