> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tomar uma decisão

> Avalie perguntas tipadas sobre o estado da aplicação com os modelos de decisão suportados.

Use `POST /v1/decisions` quando sua aplicação precisar de respostas estruturadas que o código possa consumir diretamente. Os modelos suportados incluem TypeSafe Jev 1.13 (`typesafe/jev-1.13.0`), Together Tev1 4B Experimental (`together/tev1-4b-experimental`) e Respan Span-01 (`respan/span-01:free` e `respan/span-01`).

A solicitação contém:

* `state`: uma string, objeto ou array com as informações a avaliar.
* `questions`: um mapa de perguntas nomeadas. Cada pergunta define `type` como `noul`, `choice` ou `score` e inclui `instructions`; os tipos suportados dependem do modelo selecionado.
* `model`: o identificador do modelo da Phaseo. Use `typesafe/jev-1.13.0` para Jev 1.13 ou `typesafe/jev-latest` para acompanhar a versão mais recente de Jev.

Liquid D1 (`liquid-ai/d1:free`, também disponível como `liquid-ai/d1`) e Perplexity Decider 27B (`perplexity/decider-27b`) suportam os três tipos de perguntas. D1 é gratuito durante o acesso antecipado experimental. Decider custa US\$ 0,04 por milhão de tokens de entrada, incluindo tokens de imagem; os tokens de saída são gratuitos. Adicione uma credencial do provedor Perplexity na Phaseo para usar Decider. Seu estado com imagens usa URLs de dados base64 PNG, JPEG ou WebP; URLs de imagens remotas não são suportadas. Cada pergunta de escolha aceita até 255 opções, e cada pergunta de pontuação até 10 níveis. Verifique a disponibilidade antes de chamar qualquer um dos modelos.

Para Respan Span-01, `state` deve ser um trecho de conversa com um array `input` de mensagens anteriores e uma mensagem `output` do assistente. Span-01 suporta apenas perguntas `noul`. A resposta `noul` é a probabilidade de o comportamento estar presente; `probabilities` também inclui as probabilidades de ausência e de não ser observável.

```json theme={null}
{
  "model": "respan/span-01:free",
  "state": {
    "input": [{ "role": "user", "content": "Please connect me to a person." }],
    "output": { "role": "assistant", "content": "I will connect you to support." }
  },
  "questions": {
    "escalation": {
      "type": "noul",
      "instructions": "Does the assistant offer a human handoff?"
    }
  }
}
```

`respan/span-01:free` é o modelo Lite gratuito com limite diário; a Phaseo o mapeia para o identificador de modelo API `span-01-free` da Respan. `respan/span-01` é mapeado para `span-01-pro` e cobrado pela Respan a US\$ 0,02 por milhão de tokens de entrada; os tokens de saída são gratuitos. Span-01 está em acesso antecipado, então a Respan precisa habilitar o acesso para sua organização. Adicione sua chave de API da Respan como credencial do provedor Respan na Phaseo antes de chamar esses modelos.

As respostas usam as mesmas chaves de `questions`. Respostas `choice` incluem a opção selecionada, probabilidades e confiança; respostas `noul` incluem uma probabilidade de 0 a 1; e respostas `score` incluem uma pontuação ponderada por probabilidade, legenda, probabilidades e confiança.

Para o exemplo da Respan, uma resposta tem este formato:

```json theme={null}
{
  "answers": {
    "escalation": {
      "type": "noul",
      "noul": 0.73,
      "probabilities": {
        "true": 0.73,
        "false": 0.25,
        "not_observable": 0.02
      }
    }
  }
}
```

Jev permite combinar os três tipos de perguntas em uma solicitação; Span-01 suporta apenas perguntas `noul`. Consulte o [início rápido](../../quickstart) para exemplos de cURL, JavaScript, SDK TypeScript e SDK Python prontos para copiar e colar. Jev 1.13 é cobrado a US\$ 0,042 por milhão de tokens de entrada; os tokens de saída são gratuitos.

Para a semântica das perguntas do provedor, consulte a [referência da API](https://docs.typesafe.ai/api) da TypeSafe.

### Decisões sobre imagens com Clef

`cloudflare/clef` e `cloudflare/clef-flash` suportam os três tipos de perguntas e imagens incorporadas pelo Cloudflare Workers AI. Cada um tem uma janela de contexto de 65.536 tokens. A entrada custa US$ 0,24 por milhão de tokens no Clef e US$ 0,09 no Clef Flash.

```json theme={null}
{
  "model": "cloudflare/clef-flash",
  "state": "Inspect the attached product photo.",
  "images": [{ "content_type": "image/png", "base64": "<base64 image bytes>" }],
  "questions": {
    "damaged": { "type": "noul", "instructions": "Is the product visibly damaged?" }
  }
}
```

Você também pode fornecer uma string `data:image/png;base64,...` em `images`. O Clef aceita até quatro imagens PNG, JPEG ou WebP, cada uma com no máximo 4 MiB e 16 megapixels, com até 8 MiB de dados de imagem decodificados no total e um corpo de requisição de 13 MiB. URLs remotas não são suportadas. O Cloudflare valida os formatos e dimensões das imagens. Modelos sem suporte a imagens rejeitam requisições com imagens.

O Clef aceita no máximo 64 perguntas, com IDs de até 100 letras, dígitos, sublinhados, pontos ou hífens. Perguntas de escolha exigem de 2 a 255 opções; perguntas de pontuação exigem de 2 a 10 níveis. Consulte a [documentação do Clef](https://developers.cloudflare.com/workers-ai/models/clef/) do Cloudflare.


## OpenAPI

````yaml pt-BR/openapi/v1/openapi.localized.yaml POST /decisions
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    Uma API de gateway para acessar diversos modelos de IA por meio de endpoints
    compatíveis com OpenAI.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Roteamento global
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /decisions:
    post:
      tags:
        - Gateway
      summary: Tomar decisões estruturadas
      description: >-
        Avalia perguntas tipadas Noul, Choice e Score sobre um estado
        estruturado usando um modelo de decisão como TypeSafe Jev.
      operationId: makeDecision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionsRequest'
      responses:
        '200':
          description: Resposta de decisões estruturadas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionsResponse'
components:
  schemas:
    DecisionsRequest:
      type: object
      required:
        - model
        - state
        - questions
      properties:
        model:
          type: string
          description: >-
            Identificador canônico do modelo da Phaseo ou alias do modelo do
            provedor.
          default: typesafe/jev-1.13.0
        state:
          description: Estado estruturado avaliado pelo modelo.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
            - type: array
              items: {}
        questions:
          type: object
          minProperties: 1
          maxProperties: 128
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/DecisionNoulQuestion'
              - $ref: '#/components/schemas/DecisionChoiceQuestion'
              - $ref: '#/components/schemas/DecisionScoreQuestion'
        images:
          type: array
          maxItems: 4
          description: >-
            Imagens incorporadas para modelos de decisão com capacidade visual.
            O Clef aceita PNG, JPEG ou WebP; URLs remotas não são suportadas.
            Máximo de 4 MiB e 16 megapixels por imagem, 8 MiB de dados
            decodificados no total e 13 MiB por corpo de requisição.
          items:
            oneOf:
              - type: string
                pattern: >-
                  ^[Dd][Aa][Tt][Aa]:image/(png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$
              - $ref: '#/components/schemas/DecisionImage'
        meta:
          type: boolean
          default: false
        echo_upstream_request:
          type: boolean
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
        routing:
          $ref: '#/components/schemas/ProviderRoutingOptions'
        metadata:
          type: object
          additionalProperties: true
    DecisionsResponse:
      type: object
      properties:
        model:
          type: string
        answers:
          type: object
          additionalProperties: true
        usage:
          $ref: '#/components/schemas/DecisionsUsage'
        request_id:
          type: string
          nullable: true
        meta:
          type: object
          additionalProperties: true
    DecisionNoulQuestion:
      type: object
      required:
        - type
        - instructions
      properties:
        type:
          type: string
          enum:
            - noul
        instructions:
          $ref: '#/components/schemas/DecisionInstructions'
        criteria:
          type: object
          properties:
            'true':
              type: string
            'false':
              type: string
          additionalProperties: true
    DecisionChoiceQuestion:
      type: object
      required:
        - type
        - instructions
        - criteria
      properties:
        type:
          type: string
          enum:
            - choice
        instructions:
          $ref: '#/components/schemas/DecisionInstructions'
        criteria:
          type: object
          minProperties: 1
          additionalProperties:
            type: string
            nullable: true
    DecisionScoreQuestion:
      type: object
      required:
        - type
        - instructions
        - criteria
      properties:
        type:
          type: string
          enum:
            - score
        instructions:
          $ref: '#/components/schemas/DecisionInstructions'
        criteria:
          type: array
          minItems: 2
          items:
            type: string
    DecisionImage:
      type: object
      required:
        - content_type
        - base64
      properties:
        content_type:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
        base64:
          type: string
          pattern: ^[A-Za-z0-9+/]+={0,2}$
    DebugOptions:
      type: object
      description: >-
        Controles de depuração do gateway. Essas opções nunca são encaminhadas
        ao provedor.
      properties:
        enabled:
          type: boolean
        return_upstream_request:
          type: boolean
        return_upstream_response:
          type: boolean
        trace:
          type: boolean
        trace_level:
          type: string
          enum:
            - summary
            - full
    ProviderRoutingOptions:
      type: object
      description: Preferências de roteamento de provedores para seleção pelo gateway.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: Incluir provedores alpha no roteamento (desativado por padrão).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: Permitir fallback para outro provedor elegível após uma falha.
        require_parameters:
          type: boolean
          nullable: true
          description: >-
            Exigir suporte do provedor aos parâmetros solicitados antes do
            roteamento.
        required_execution_region:
          type: string
          nullable: true
          description: >-
            Restringir o roteamento a provedores com a região de execução
            solicitada.
        required_data_region:
          type: string
          nullable: true
          description: >-
            Restringir o roteamento a provedores com a região de dados
            solicitada.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: >-
            Restringir o roteamento a provedores que oferecem retenção zero de
            dados.
        data_collection:
          type: string
          nullable: true
          enum:
            - allow
            - deny
        zdr:
          type: boolean
          nullable: true
        enforce_distillable_text:
          type: boolean
          nullable: true
        quantizations:
          type: array
          nullable: true
          items:
            type: string
        sort:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Classificar os provedores para esta solicitação, por exemplo, por
            preço, latência ou throughput.
        max_price:
          type: object
          properties:
            prompt:
              oneOf:
                - type: number
                - type: string
            completion:
              oneOf:
                - type: number
                - type: string
            image:
              oneOf:
                - type: number
                - type: string
            audio:
              oneOf:
                - type: number
                - type: string
            request:
              oneOf:
                - type: number
                - type: string
        preferred_min_throughput:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
        preferred_max_latency:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
    DecisionsUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        total_tokens:
          type: integer
          minimum: 0
    DecisionInstructions:
      oneOf:
        - type: string
        - type: object
          additionalProperties: true
        - type: array
          items: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Autenticação com token Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.