Guía de integración de la API de destino

Método de acceso, modelos disponibles, especificación de solicitudes, reglas de cobro y ejemplos para la API de destino de YlanAI

mar. 25, 2026

Esta página describe la forma estándar de integrar la API de destino de YlanAI.

La interfaz actual sigue el protocolo compatible con OpenAI y está orientada a clientes que admiten chat/completions y completions.

1. Información de acceso

URL, método de solicitud y endpoints estándar

Elemento	Descripción
URL base recomendada	`https://ylan.ai/api/openai`
URL base compatible	`https://ylan.ai/api/openai/v1`
Método por defecto	`POST`
Lista de modelos	`GET /models`
Detalle de modelo	`GET /models/{id}`
Endpoint de conversación	`POST /chat/completions`
Endpoint heredado `completions`	`POST /completions`

Para clientes que agregan /v1 automáticamente, usa preferentemente https://ylan.ai/api/openai.

Autenticación

Todas las solicitudes deben incluir:

Authorization: Bearer sk-...

La API key pertenece a la cuenta del usuario actual y el consumo se descuenta del saldo de créditos pagados de esa cuenta.

Para clientes de terceros que no puedan establecer Authorization, también se aceptan los encabezados de compatibilidad api-key: sk-... y x-api-key: sk-....

Conversación multi-turno

Se admite conversación de varias rondas. El cliente puede mantener el contexto enviando el historial dentro del arreglo messages.

2. Alcance y modelos

Alcance del servicio

Alcance	Descripción
Capacidad expuesta	Solo está abierta la API de análisis de destino
Chat general	No disponible
Escenarios compatibles	Análisis individual y análisis de pareja
Estándar de salida	Alineado con la experiencia interna del producto

Modelos disponibles

La referencia oficial es el resultado en tiempo real de GET /models. El conjunto disponible puede actualizarse según la evolución de la plataforma.

Modelo	Descripción
`openai/gpt-5.4`	Adecuado para análisis de destino de alta exigencia
`openai/gpt-5.3-chat`	Adecuado para interpretación general y diálogo multi-turno
`deepseek/deepseek-v3.2`	Adecuado para análisis diversos y diálogo multi-turno

3. Especificación de la solicitud

Formato de respuesta

Escenario	Formato de respuesta
`stream=true`	Flujo SSE compatible con OpenAI con cargas `chat.completion.chunk` y cierre `data: [DONE]`
`stream=false`	Respuesta JSON estándar `chat.completion`
`POST /completions`	Respuesta JSON `text_completion` compatible con OpenAI o flujo SSE
Cabeceras non-stream exitosas	`x-ylan-charged-credits` y `x-ylan-remaining-paid-credits`

Parámetros de solicitud

Parámetro	Tipo	Descripción
`model`	`string`	Nombre del modelo devuelto por `GET /models`
`messages`	`array`	Arreglo de mensajes compatible con OpenAI; debe incluir al menos un mensaje `user`
`prompt`	`string`	Entrada heredada de `completions`; puede usarse cuando no se envía `messages`
`input`	`string`	Campo de entrada compatible con algunos clientes de terceros cuando no se envía `messages`
`stream`	`boolean`	Si se usa salida streaming; valor por defecto `false`
`locale`	`string`	Idioma de salida, como `es`, `zh` o `en`
`topic`	`string`	Tema de destino, como `wealth_pattern` o `marriage_status`
`subject_mode`	`string`	Modo de análisis, `single` o `pair`
`method`	`string`	Método de análisis resuelto por la cadena actual
`birth_profile`	`object`	Entrada para análisis individual con datos de nacimiento
`chart_input`	`object`	Entrada estructurada para escenarios con carta ya preparada
`pair_state`	`object`	Entrada para análisis de pareja
`metadata`	`object`	Metadatos extendidos que pueden complementar `topic`, `locale`, `birthProfile`, `pairState` y otros campos

Ejemplo streaming individual

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": "es",
    "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": "Analiza mi tendencia financiera para este año."
      }
    ]
  }'

Ejemplo streaming de pareja

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": "es",
    "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": "Analiza la dirección a largo plazo de esta relación y los puntos clave de compatibilidad."
      }
    ]
  }'

4. Cobro y tratamiento de errores

Reglas de cobro y momento de confirmación

Escenario	Regla
Análisis individual	100 créditos por cada respuesta exitosa
Análisis de pareja	200 créditos por cada respuesta exitosa
`need_input`	No genera cobro
Alcance de créditos	Solo se consumen créditos pagados; los bonos de registro y créditos regalados quedan excluidos
`stream=true`	El cobro se confirma cuando llega el primer contenido visible válido
`stream=false`	El cobro se confirma cuando la respuesta completa se devuelve correctamente
Timeout, fallo, respuesta vacía	El cobro no se confirma o se revierte según la regla actual

Códigos de error comunes

Estado HTTP	Código de error	Descripción
`400`	`invalid_messages`	La solicitud no contiene mensajes válidos o falta un mensaje `user`
`400`	`invalid_prompt`	La solicitud no incluye `messages`, `prompt` ni `input`
`400`	`invalid_model`	El modelo solicitado no está dentro de la lista permitida
`401`	`invalid_api_key`	La API key es inválida o no fue enviada
`402`	`insufficient_paid_credits`	La cuenta no tiene suficientes créditos pagados
`500`	`request_timeout`	La solicitud agotó el tiempo
`500`	`request_failed`	La solicitud falló
`500`	`internal_error`	Error interno del servidor
`502`	`empty_response`	El modelo no devolvió contenido visible válido

Respuesta need_input

Cuando faltan datos de nacimiento, datos temáticos o información de pareja, la API puede devolver una respuesta de tipo need_input. Este tipo de respuesta solo sirve para completar las condiciones previas del análisis y no genera cobro.