Guia de Integração da API de Destino

Forma de acesso, modelos disponíveis, especificação das requisições, regras de cobrança e exemplos de uso da API de destino da YlanAI

mar 25, 2026

Esta página descreve o padrão de integração da API de destino da YlanAI.

A interface atual segue o protocolo compatível com OpenAI e foi pensada para clientes que suportem chat/completions e completions.

1. Informações de acesso

URL, método de requisição e endpoints padrão

Item	Descrição
URL base recomendada	`https://ylan.ai/api/openai`
URL base de compatibilidade	`https://ylan.ai/api/openai/v1`
Método padrão	`POST`
Lista de modelos	`GET /models`
Detalhe do modelo	`GET /models/{id}`
Endpoint de conversa	`POST /chat/completions`
Endpoint legado `completions`	`POST /completions`

Para clientes de terceiros que acrescentam /v1 automaticamente, use https://ylan.ai/api/openai como URL base configurada.

Autenticação

Todas as requisições devem incluir:

Authorization: Bearer sk-...

A API key pertence à conta do usuário atual, e o consumo é debitado do saldo de créditos pagos dessa conta.

Para clientes que não conseguem definir Authorization, a compatibilidade também aceita api-key: sk-... e x-api-key: sk-....

Conversa multi-turn

Conversas em múltiplas rodadas são suportadas. O cliente pode enviar o histórico no array messages para preservar o contexto.

2. Escopo e modelos

Escopo do serviço

Escopo	Descrição
Capacidade exposta	Apenas a API de análise de destino está aberta
Chat geral	Não está disponível
Cenários suportados	Há suporte para análise individual e análise de casal
Padrão de saída	Segue a mesma referência do produto interno

Modelos disponíveis

O resultado em tempo real de GET /models é a referência oficial. O conjunto disponível pode mudar conforme a evolução da plataforma.

Modelo	Descrição
`openai/gpt-5.4`	Adequado para análises de destino com maior exigência de qualidade
`openai/gpt-5.3-chat`	Adequado para interpretação geral e diálogo multi-turno
`deepseek/deepseek-v3.2`	Adequado para análises variadas e diálogo multi-turno

3. Especificação da requisição

Formato de resposta

Cenário	Formato de resposta
`stream=true`	Retorna um fluxo SSE compatível com OpenAI usando payloads `chat.completion.chunk` e encerramento com `data: [DONE]`
`stream=false`	Retorna um JSON padrão `chat.completion`
`POST /completions`	Retorna um JSON `text_completion` compatível com OpenAI ou fluxo SSE
Headers non-stream bem-sucedidos	Inclui `x-ylan-charged-credits` e `x-ylan-remaining-paid-credits`

Parâmetros da requisição

Parâmetro	Tipo	Descrição
`model`	`string`	Nome do modelo retornado por `GET /models`
`messages`	`array`	Array de mensagens compatível com OpenAI; é necessário ao menos um item `user`
`prompt`	`string`	Entrada legada de `completions`; pode ser usada quando `messages` é omitido
`input`	`string`	Campo de entrada de compatibilidade para alguns clientes terceiros quando `messages` é omitido
`stream`	`boolean`	Define se a resposta será em streaming. O padrão é `false`
`locale`	`string`	Idioma de saída, como `pt`, `zh` ou `en`
`topic`	`string`	Tema de destino, como `wealth_pattern` ou `marriage_status`
`subject_mode`	`string`	Modo de análise: `single` ou `pair`
`method`	`string`	Método de análise interpretado pela cadeia atual
`birth_profile`	`object`	Entrada com dados de nascimento para análise individual
`chart_input`	`object`	Entrada estruturada para cenários com mapa já preparado
`pair_state`	`object`	Entrada para análise de casal
`metadata`	`object`	Metadados estendidos que podem complementar `topic`, `locale`, `birthProfile`, `pairState` e outros campos

Exemplo 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": "pt",
    "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": "Analise minha tendência financeira para este ano."
      }
    ]
  }'

Exemplo streaming de casal

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": "pt",
    "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": "Analise a direção de longo prazo desta relação e os principais pontos de compatibilidade."
      }
    ]
  }'

4. Cobrança e tratamento de erros

Regras de cobrança e momento de confirmação

Cenário	Regra
Análise individual	100 créditos por resposta bem-sucedida
Análise de casal	200 créditos por resposta bem-sucedida
`need_input`	Não gera cobrança
Escopo dos créditos	Apenas créditos pagos podem ser consumidos; bônus de cadastro e créditos concedidos não são aceitos
`stream=true`	A cobrança é confirmada quando o primeiro conteúdo visível válido é retornado
`stream=false`	A cobrança é confirmada depois que a resposta completa é retornada com sucesso
Timeout, falha ou resposta vazia	A cobrança não é confirmada ou é revertida conforme a regra vigente

Códigos de erro comuns

Status HTTP	Código de erro	Descrição
`400`	`invalid_messages`	A requisição não contém mensagens válidas ou não possui mensagem `user`
`400`	`invalid_prompt`	A requisição não contém `messages`, `prompt` nem `input`
`400`	`invalid_model`	O modelo solicitado não está na allowlist atual
`401`	`invalid_api_key`	A API key está ausente ou inválida
`402`	`insufficient_paid_credits`	A conta não possui créditos pagos suficientes
`500`	`request_timeout`	A requisição excedeu o tempo limite
`500`	`request_failed`	A requisição falhou
`500`	`internal_error`	Erro interno do servidor
`502`	`empty_response`	O modelo não retornou conteúdo visível válido

Respostas need_input

Quando dados de nascimento, dados do tópico ou informações de casal estão incompletos, a API pode retornar uma resposta no estilo need_input. Esse tipo de resposta serve apenas para complementar os pré-requisitos da análise e não é cobrado.