Guide d'intégration de l'API de destinée

Mode d'accès, modèles disponibles, spécification des requêtes, règles de facturation et exemples pour l'API de destinée YlanAI

mars 25, 2026

Cette page présente la méthode standard d'intégration de l'API de destinée YlanAI.

L'interface actuelle suit le protocole compatible OpenAI et s'adresse aux clients prenant en charge chat/completions et completions.

1. Informations d'accès

URL, méthode de requête et endpoints standard

Élément	Description
URL de base recommandée	`https://ylan.ai/api/openai`
URL de base compatible	`https://ylan.ai/api/openai/v1`
Méthode par défaut	`POST`
Liste des modèles	`GET /models`
Détail d’un modèle	`GET /models/{id}`
Endpoint de dialogue	`POST /chat/completions`
Endpoint legacy `completions`	`POST /completions`

Pour les clients qui ajoutent /v1 automatiquement, utilisez en priorité https://ylan.ai/api/openai.

Authentification

Chaque requête doit inclure :

Authorization: Bearer sk-...

La clé API est rattachée au compte utilisateur courant, et les consommations sont déduites du pool de crédits payants de ce compte.

Pour les clients tiers qui ne peuvent pas définir Authorization, les en-têtes de compatibilité api-key: sk-... et x-api-key: sk-... sont également acceptés.

Conversation multi-tour

La conversation multi-tour est prise en charge. Le client peut transmettre l'historique via le tableau messages afin de conserver le contexte.

2. Portée et modèles

Portée du service

Portée	Description
Capacité exposée	Seule l'API d'analyse de destinée est exposée
Chat général	Non disponible
Scénarios pris en charge	Analyse mono-sujet et analyse à deux sujets
Standard de sortie	Aligné avec l'expérience interne du produit

Modèles disponibles

La référence fait foi via GET /models. L'ensemble disponible peut évoluer selon la feuille de route produit.

Modèle	Description
`openai/gpt-5.4`	Adapté aux analyses de destinée à forte exigence de qualité
`openai/gpt-5.3-chat`	Adapté aux analyses générales et aux échanges multi-tour
`deepseek/deepseek-v3.2`	Adapté aux analyses variées et aux échanges multi-tour

3. Spécification des requêtes

Format de réponse

Cas	Format de réponse
`stream=true`	Flux SSE compatible OpenAI avec payloads `chat.completion.chunk` et marqueur final `data: [DONE]`
`stream=false`	Réponse JSON standard `chat.completion`
`POST /completions`	Réponse JSON `text_completion` compatible OpenAI ou flux SSE
En-têtes non-stream réussis	`x-ylan-charged-credits` et `x-ylan-remaining-paid-credits`

Paramètres de requête

Paramètre	Type	Description
`model`	`string`	Nom du modèle retourné par `GET /models`
`messages`	`array`	Tableau de messages compatible OpenAI ; au moins un message `user` est requis
`prompt`	`string`	Entrée legacy `completions`, utilisable si `messages` est omis
`input`	`string`	Champ d’entrée compatible avec certains clients tiers si `messages` est omis
`stream`	`boolean`	Active ou non le mode stream ; valeur par défaut `false`
`locale`	`string`	Langue de sortie, par exemple `fr`, `zh`, `en`
`topic`	`string`	Sujet de destinée, par exemple `wealth_pattern` ou `marriage_status`
`subject_mode`	`string`	Mode d'analyse, `single` ou `pair`
`method`	`string`	Méthode d'analyse interprétée par la chaîne métier actuelle
`birth_profile`	`object`	Données de naissance pour une analyse mono-sujet
`chart_input`	`object`	Données structurées de thème pour un scénario déjà pré-calculé
`pair_state`	`object`	Données d'entrée pour l'analyse à deux sujets
`metadata`	`object`	Métadonnées étendues pouvant compléter `topic`, `locale`, `birthProfile`, `pairState`, etc.

Exemple stream mono-sujet

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-5.4",
    "stream": true,
    "locale": "fr",
    "topic": "wealth_pattern",
    "subject_mode": "single",
    "birth_profile": {
      "calendar": "solar",
      "birthDate": "1992-08-15",
      "birthTime": "09:30",
      "gender": "male",
      "location": "Shenzhen"
    },
    "messages": [
      {
        "role": "user",
        "content": "Veuillez analyser ma tendance financière pour cette année."
      }
    ]
  }'

Exemple stream analyse à deux sujets

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek/deepseek-v3.2",
    "stream": true,
    "locale": "fr",
    "topic": "marriage_status",
    "subject_mode": "pair",
    "pair_state": {
      "subjects": [
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1992-08-15",
            "birthTime": "09:30",
            "gender": "male",
            "location": "Shenzhen"
          }
        },
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1995-03-08",
            "birthTime": "22:15",
            "gender": "female",
            "location": "Guangzhou"
          }
        }
      ]
    },
    "messages": [
      {
        "role": "user",
        "content": "Veuillez analyser la direction à long terme de cette relation et les points clés de compatibilité."
      }
    ]
  }'

4. Facturation et gestion des erreurs

Règles de facturation et moment de confirmation

Cas	Règle
Analyse mono-sujet	100 crédits par réponse réussie
Analyse à deux sujets	200 crédits par réponse réussie
`need_input`	Non facturé
Portée des crédits	Seuls les crédits payants sont consommés ; crédits de bienvenue et crédits offerts exclus
`stream=true`	La facturation est confirmée dès le premier contenu visible
`stream=false`	La facturation est confirmée après la réponse complète et réussie
Timeout, échec, réponse vide	La facturation n'est pas confirmée ou est remboursée selon la règle actuelle

Codes d'erreur courants

Statut HTTP	Code d'erreur	Description
`400`	`invalid_messages`	La requête ne contient pas de message valide ou aucun message `user`
`400`	`invalid_prompt`	La requête ne contient ni `messages`, ni `prompt`, ni `input`
`400`	`invalid_model`	Le modèle demandé n'est pas autorisé
`401`	`invalid_api_key`	La clé API est absente ou invalide
`402`	`insufficient_paid_credits`	Le compte ne dispose pas d'assez de crédits payants
`500`	`request_timeout`	La requête a expiré
`500`	`request_failed`	La requête a échoué
`500`	`internal_error`	Erreur interne du serveur
`502`	`empty_response`	Le modèle n'a renvoyé aucun contenu visible

Réponses need_input

Lorsque les informations de naissance, de sujet ou de pair sont incomplètes, l'API peut renvoyer une réponse de type need_input. Cette réponse sert uniquement à compléter les prérequis d'analyse et n'est pas facturée.