Come usare deepseek-v4.1-flash tramite l'API hiapi: curl, Python ed esempi di richiesta funzionanti

deepseek-v4.1-flash è un modello di inferenza veloce ed economico, richiamabile tramite l'API unificata di hiapi. Attualmente è contrassegnato come anteprima (Preview) nella pagina del modello, il che significa che la build sottostante può essere soggetta a rotazione, mentre l'ID pubblico del modello (deepseek-v4.1-flash) rimane stabile: quando avviene la rotazione non devi modificare alcun codice. Questa guida mostra una richiesta effettivamente funzionante: l'endpoint corretto, i campi corretti, le intestazioni di autenticazione corrette.

Prerequisiti

• Una chiave API hiapi (sk-...). Ottienila dalla tua console hiapi, poi esportala:

export HIAPI_API_KEY="sk-your-key-here"

• Qualsiasi client HTTP va bene. Gli esempi seguenti usano curl e la libreria Python requests, con indicazioni per l'uso dell'SDK ufficiale OpenAI.

Esempio minimo funzionante

hiapi fornisce due endpoint di testo. /v1/responses è l'endpoint canonico consigliato (forma OpenAI Responses API, eventi SSE semantici). /v1/chat/completions è l'endpoint compatibile con le versioni precedenti (forma OpenAI Chat Completions) — usalo solo se stai migrando un'integrazione esistente basata su Chat Completions. Questa guida usa /v1/responses.

curl

curl https://api.hiapi.ai/v1/responses \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "input": [
      {"role": "user", "content": "Explain what a hash map is in two sentences."}
    ]
  }'

Una risposta riuscita restituisce un array output contenente la risposta del modello, oltre a un blocco usage:

{
  "id": "resp_...",
  "model": "deepseek-v4.1-flash-expires-on-0910",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "A hash map stores key-value pairs..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 42,
    "total_tokens": 56,
    "output_tokens_details": {"reasoning_tokens": 0}
  }
}

Nota che il campo model nella risposta è contrassegnato come deepseek-v4.1-flash-expires-on-0910 — è la build interna fissa che attualmente serve questo modello in anteprima. Questo è il comportamento previsto per i modelli in anteprima su hiapi, non un segnale che il modello sta per essere ritirato; continua a richiedere l'ID nudo deepseek-v4.1-flash e hiapi ti indirizzerà automaticamente alla build corrente.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [
            {"role": "user", "content": "Explain what a hash map is in two sentences."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["output"][0]["content"][0]["text"])
print(data["usage"])

Uso dell'SDK OpenAI

/v1/responses e /v1/chat/completions di hiapi sono compatibili con l'SDK ufficiale OpenAI — basta puntare il base URL a hiapi e mantenere l'ID del modello come nome nudo:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)
resp = client.responses.create(
    model="deepseek-v4.1-flash",
    input=[{"role": "user", "content": "Explain what a hash map is in two sentences."}],
)
print(resp.output[0].content[0].text)

Pratiche per l'ambiente di produzione

Le richieste sono stateless — occorre riprodurre l'intera conversazione

hiapi non conserva lo stato della conversazione lato server per questo modello. Ogni richiesta deve includere l'intera cronologia dei messaggi in input. Non inviare store, previous_response_id, conversation, background o context_management — nessuno di questi è supportato e verranno ignorati o rifiutati. Per le conversazioni multi-turno, aggiungi tu stesso ogni nuovo messaggio user/assistant all'array input e invia l'intero array a ogni richiesta.

history = [{"role": "user", "content": "What's a hash map?"}]
# ... call, get a reply, then append it and the next question ...
history.append({"role": "assistant", "content": "<model's previous reply>"})
history.append({"role": "user", "content": "How is that different from a hash set?"})

Intensità di ragionamento

deepseek-v4.1-flash accetta un oggetto reasoning che controlla quanto ragionamento interno svolge prima di rispondere. L'enumerazione effort per questo modello è none | high | max — nota che non è il livello low/medium/high usato da alcuni altri modelli di ragionamento su hiapi, quindi non dare per scontato che sia direttamente applicabile.

{
  "model": "deepseek-v4.1-flash",
  "input": [{"role": "user", "content": "Prove that the square root of 2 is irrational."}],
  "reasoning": {"effort": "high"}
}

I token di ragionamento vengono fatturati come token di output e riportati separatamente in usage.output_tokens_details.reasoning_tokens, quindi le richieste con intensità high/max possono essere significativamente più costose di none anche se la risposta visibile ha la stessa lunghezza. Prima di impostare un'intensità predefinita per il traffico di produzione, controlla le tariffe correnti per token nella pagina dei prezzi.

Streaming

Passa "stream": true per ottenere Server-Sent Events invece di un singolo blocco JSON. Lo streaming di /v1/responses utilizza eventi semantici, non incrementi di testo grezzi racchiusi in marcatori [DONE] in stile Chat-Completions. La sequenza di eventi per un completamento normale è:

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta   (repeated, one per chunk of text)
response.output_text.done
response.content_part.done
response.output_item.done
response.completed

Tratta response.completed come evento di terminazione riuscita. Tratta anche response.incomplete (ad esempio, raggiungimento dei limiti di token/lunghezza) e response.failed (errori lato server) come stati di terminazione — non dare per scontato che ogni stream termini con response.completed.

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [{"role": "user", "content": "Count to 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as r:
    for line in r.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        event = json.loads(line[len(b"data: "):])
        if event.get("type") == "response.output_text.delta":
            print(event["delta"], end="", flush=True)
        elif event.get("type") in ("response.completed", "response.incomplete", "response.failed"):
            break

Gestione degli errori

Una chiave API non valida o mancante restituisce HTTP 401, con un corpo di risposta di errore strutturato:

{"error": {"code": "permission_denied", "message": "..."}}

Controlla resp.status_code e gestisci in base a error.code, invece di analizzare la stringa del messaggio, poiché il testo del messaggio può cambiare formulazione senza preavviso.

Documentazione correlata

• Pagina del modello deepseek-v4.1-flash
• Riferimento /v1/responses
• Riferimento /v1/chat/completions
• Autenticazione
• Prezzi

Domande frequenti

deepseek-v4.1-flash è utilizzabile in produzione o solo per test? È contrassegnato come anteprima, il che su hiapi significa che il modello è attivo e richiamabile correttamente, ma la build sottostante può essere soggetta a rotazione secondo le disposizioni di hiapi. L'ID pubblico del modello non cambia durante la rotazione — il tuo codice continuerà a funzionare senza modifiche. Se hai bisogno di una garanzia formale non di anteprima, consulta le varianti DeepSeek v4 non in anteprima nell'elenco dei modelli.

Perché la risposta mostra un nome di modello diverso da quello che ho richiesto? Nel campo model della risposta vedrai un valore come deepseek-v4.1-flash-expires-on-0910. È la build fissa specifica che attualmente serve la tua richiesta sotto l'ID deepseek-v4.1-flash — questo è il comportamento previsto per i modelli in anteprima, non un errore.

Posso usare /v1/chat/completions invece di /v1/responses? Sì, hiapi supporta entrambi per questo modello. /v1/chat/completions usa la forma di richiesta/risposta di OpenAI Chat Completions (array messages, choices[0].message.content), invece della forma input/output di /v1/responses. Scegli quella che corrisponde alla tua integrazione esistente; le nuove integrazioni dovrebbero usare /v1/responses come impostazione predefinita.

hiapi memorizza la mia cronologia delle conversazioni, così posso inviare solo l'ultimo messaggio? No. Questo modello non ha previous_response_id né stato della conversazione lato server — a ogni richiesta devi inviare l'intera cronologia dei messaggi in input.

Cosa salta effettivamente reasoning.effort: "none"? Salta completamente il processo di ragionamento interno del modello e risponde direttamente. Per i compiti che traggono beneficio dal ragionamento multi-step (matematica, logica con più vincoli), usa "high" o "max"; intensità più elevate aumentano di conseguenza il consumo di token di output e la latenza.

Le richieste in streaming e quelle non in streaming richiedono chiavi API separate? No — la stessa chiave Authorization: Bearer sk-... funziona per entrambe. Lo streaming è controllato interamente dal campo "stream": true nel corpo della richiesta.