Jobs asynchrones

Exécute une chat completion en tâche de fond : la requête est acceptée immédiatement (202 + identifiant job_…), traitée par nos workers, et le résultat se récupère par polling. C'est la voie recommandée pour toute génération susceptible de dépasser ~100 secondes.

Principe#principe

En mode synchrone non streamé, l'infrastructure coupe toute requête restée ~100 s sans octet transmis (erreur 524) — typiquement une génération longue avec effort: high ou une sortie volumineuse. Le mode background découple la soumission de l'exécution :

• 1. POST /v1/chat/completions avec "background": true → réponse immédiate 202 avec un job_….
• 2. Le job est exécuté en arrière-plan, avec le même timeout que le mode synchrone (600 s par défaut).
• 3. GET /v1/jobs/{id} → statut, puis résultat complet (shape chat.completion identique au synchrone) une fois terminé.
• 4. DELETE /v1/jobs/{id} → annule un job encore en attente, ou efface un job terminé sans attendre la purge.

Soumission (background)#soumission

Tous les paramètres de Chat completions s'appliquent — seuls changent :

curl https://ai.3gks.cloud/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-3gk-7XQp4kL8…" \
  -d '{
    "model": "3gk-llm",
    "messages": [
      {"role": "user", "content": "Analyse ce dossier complet : …"}
    ],
    "effort": "high",
    "max_tokens": 4096,
    "background": true
  }'

Récupérer le résultat#polling

Tant que le job est queued ou running, la réponse ne contient ni result ni error. Une fois succeeded, result contient la complétion complète — champs choices, usage, reasoning identiques au mode synchrone. Un job encore en attente passe en cancelled (avec un bloc error de code cancelled) si la clé API qui l'a soumis est révoquée ou le compte suspendu : il n'est ni exécuté ni facturé. Cadence conseillée : toutes les 2 à 5 s, avec backoff si vos jobs durent plusieurs minutes.

curl https://ai.3gks.cloud/v1/jobs/job_a1b2c3d4e5f60718 \
  -H "Authorization: Bearer sk-3gk-7XQp4kL8…"

Annuler ou supprimer un job

Même périmètre que le polling : seule la clé qui a soumis le job peut le supprimer (404 sinon). Le comportement dépend du statut :

• queued → job annulé avant exécution : 200 avec { "id": "job_…", "status": "cancelled" }. Il n'est ni exécuté ni facturé, et son prompt est effacé.
• running → 409 invalid_request : la génération est en cours, attendez la fin puis rappelez DELETE.
• succeeded / failed / cancelled → la ligne est supprimée (requête et résultat) sans attendre la purge à 7 jours : 200 avec { "id": "job_…", "deleted": true }.

Lister ses jobs#liste

Renvoie { object: "list", data: [ … ] } — les jobs soumis avec la clé API appelante (et non ceux du compte entier), du plus récent au plus ancien, sans le champ result (récupérez-le job par job).

Cycle de vie & statuts#statuts

Exemples#exemples

import time
import httpx

BASE = "https://ai.3gks.cloud/v1"
HEADERS = {"Authorization": "Bearer sk-3gk-7XQp4kL8…"}

# 1. Soumission — réponse immédiate (202)
job = httpx.post(f"{BASE}/chat/completions", headers=HEADERS, json={
    "model": "3gk-llm",
    "messages": [{"role": "user", "content": "Analyse ce dossier : …"}],
    "background": True,
}).json()

# 2. Polling — 3 s d'intervalle, à adapter à vos durées
while True:
    state = httpx.get(f"{BASE}/jobs/{job['id']}", headers=HEADERS).json()
    if state["status"] in ("succeeded", "failed"):
        break
    time.sleep(3)

if state["status"] == "succeeded":
    print(state["result"]["choices"][0]["message"]["content"])
else:
    print("Échec :", state["error"]["message"])

Codes de réponse#status

Pour le détail du format d'erreur, voir Codes d'erreur.