Comment utiliser deepseek-v4.1-flash via l'API hiapi : curl, Python et exemples de requêtes fonctionnelles

deepseek-v4.1-flash est un modèle de raisonnement rapide et économique, accessible via l'API unifiée hiapi. Il est actuellement marqué comme aperçu (Preview) sur la page du modèle, ce qui signifie que la construction sous-jacente peut être renouvelée tandis que l'ID de modèle public (deepseek-v4.1-flash) reste stable — vous n'avez aucun code à modifier lorsqu'un renouvellement survient. Ce guide présente une requête réellement fonctionnelle : le bon point de terminaison, les bons champs, le bon en-tête d'authentification.

Prérequis

• Une clé API hiapi (sk-...). Récupérez-la depuis votre console hiapi, puis exportez-la :

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

• N'importe quel client HTTP convient. Les exemples ci-dessous utilisent curl et requests de Python, avec des instructions pour utiliser le SDK OpenAI officiel.

Exemple minimal fonctionnel

hiapi fournit deux points de terminaison texte. /v1/responses est le point de terminaison canonique recommandé (forme OpenAI Responses API, événements SSE sémantiques). /v1/chat/completions est le point de terminaison de compatibilité héritée (forme OpenAI Chat Completions) — à utiliser uniquement lorsque vous portez une intégration Chat Completions existante. Ce guide utilise /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."}
    ]
  }'

Une réponse réussie renvoie un tableau output contenant la réponse du modèle, ainsi qu'un bloc 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}
  }
}

Remarquez que le champ model de la réponse est marqué deepseek-v4.1-flash-expires-on-0910 — il s'agit de la construction interne fixe qui sert actuellement ce modèle en aperçu. C'est le comportement attendu des modèles en aperçu sur hiapi, et non le signe d'une dépréciation imminente du modèle ; continuez à demander l'ID nu deepseek-v4.1-flash, et hiapi vous routera automatiquement vers la construction actuelle.

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"])

Utiliser le SDK OpenAI

Les points de terminaison /v1/responses et /v1/chat/completions de hiapi sont compatibles avec le SDK OpenAI officiel — il suffit de pointer l'URL de base vers hiapi et de conserver l'ID de modèle nu :

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)

Pratiques en production

Les requêtes sont sans état — il faut rejouer la conversation complète

hiapi ne conserve pas d'état de conversation côté serveur pour ce modèle. Chaque requête doit inclure dans input l'historique complet des messages. N'envoyez pas store, previous_response_id, conversation, background ni context_management — aucun n'est pris en charge et ils seront ignorés ou rejetés. Pour les conversations à plusieurs tours, ajoutez vous-même chaque nouveau message user/assistant au tableau input et envoyez le tableau entier à chaque requête.

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é de raisonnement

deepseek-v4.1-flash accepte un objet reasoning qui contrôle combien de raisonnement interne il effectue avant de répondre. L'énumération effort de ce modèle est none | high | max — notez qu'il ne s'agit pas des niveaux low/medium/high utilisés par certains autres modèles de raisonnement sur hiapi, alors ne supposez pas qu'elle s'applique telle quelle.

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

Les tokens de raisonnement sont facturés comme des tokens de sortie et reportés séparément dans usage.output_tokens_details.reasoning_tokens, donc les requêtes avec une intensité high/max peuvent être sensiblement plus coûteuses que none, même lorsque la longueur de la réponse visible est identique. Avant de définir une intensité par défaut pour le trafic de production, consultez les tarifs actuels par token sur la page de tarification.

Diffusion en continu (streaming)

Passez "stream": true pour recevoir des Server-Sent Events au lieu d'un bloc JSON unique. /v1/responses diffuse des événements sémantiques, et non des deltas de texte bruts enveloppés dans des marqueurs [DONE] de style Chat-Completions. La séquence d'événements d'une complétion normale réussie est la suivante :

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

Traitez response.completed comme l'événement de terminaison de succès. Traitez également response.incomplete (par ex. limite de tokens/longueur atteinte) et response.failed (erreur serveur) comme états de terminaison — ne supposez pas que chaque flux se termine par 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

Gestion des erreurs

Une clé API invalide ou manquante renvoie un HTTP 401 avec un corps d'erreur structuré :

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

Vérifiez resp.status_code et branchez sur error.code, plutôt que d'analyser la chaîne de message, car la formulation du message peut changer sans préavis.

Documentation associée

• Page du modèle deepseek-v4.1-flash
• Référence de /v1/responses
• Référence de /v1/chat/completions
• Authentification
• Tarification

Questions fréquentes

deepseek-v4.1-flash est-il destiné à la production ou uniquement aux tests ? Il est marqué comme aperçu, ce qui, sur hiapi, signifie que le modèle est en ligne et peut être appelé normalement, mais que la construction sous-jacente peut être renouvelée selon le calendrier de hiapi. Lors d'un renouvellement, l'ID de modèle public ne change pas — votre code continue de fonctionner sans modification. Si vous avez besoin d'un engagement formel non lié à un aperçu, consultez les variantes DeepSeek v4 non-preview de la liste des modèles.

Pourquoi la réponse affiche-t-elle un nom de modèle différent de celui que j'ai demandé ? Vous verrez dans le champ model de la réponse une valeur comme deepseek-v4.1-flash-expires-on-0910. C'est la construction fixe spécifique qui sert actuellement vos requêtes sous l'ID deepseek-v4.1-flash — c'est le comportement attendu d'un modèle en aperçu, pas une erreur.

Puis-je utiliser /v1/chat/completions au lieu de /v1/responses ? Oui, hiapi prend en charge les deux pour ce modèle. /v1/chat/completions utilise la forme requête/réponse d'OpenAI Chat Completions (tableau messages, choices[0].message.content), et non la forme input/output de /v1/responses. Choisissez celle qui correspond à votre intégration existante ; les nouvelles intégrations devraient utiliser /v1/responses par défaut.

hiapi stocke-t-il mon historique de conversation, pour que je n'envoie que le dernier message ? Non. Ce modèle n'a pas de previous_response_id ni d'état de conversation côté serveur — envoyez l'historique complet des messages dans input à chaque requête.

Que saute réellement reasoning.effort: "none" ? Il saute entièrement le processus de raisonnement interne du modèle et répond directement. Pour les tâches qui bénéficient d'un raisonnement en plusieurs étapes (mathématiques, logique à contraintes multiples), utilisez "high" ou "max" ; une intensité plus élevée augmente en conséquence l'usage de tokens de sortie et la latence.

Les requêtes en streaming et non-streaming nécessitent-elles des clés API distinctes ? Non — la même clé Authorization: Bearer sk-... fonctionne pour les deux. Le streaming est entièrement contrôlé par le champ "stream": true dans le corps de la requête.