Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Documentazione di riferimento delle API
Guida di riferimento alle API

I modelli Amazon Nova SageMaker utilizzano l'API SageMaker Runtime standard per l'inferenza. Per la documentazione completa sull'API, consulta [Testare un modello distribuito](https://docs.aws.amazon.com//sagemaker/latest/dg/realtime-endpoints-test-endpoints.html).

## Richiamata degli endpoint


I modelli Amazon Nova SageMaker supportano due metodi di invocazione:
+ **Richiamata sincrona: utilizza l'[InvokeEndpoint](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)**API per richieste di inferenza in tempo reale e non in streaming.
+ **Richiamata in streaming: utilizza l'API per le richieste di** inferenza in streaming in tempo reale [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html).

## Formato della richiesta


I modelli Amazon Nova supportano due formati di richiesta:

**Formato di completamento della chat**

Usa questo formato per le interazioni conversazionali:

```
{
  "messages": [
    {"role": "user", "content": "string"}
  ],
  "max_tokens": integer,
  "max_completion_tokens": integer,
  "stream": boolean,
  "temperature": float,
  "top_p": float,
  "top_k": integer,
  "logprobs": boolean,
  "top_logprobs": integer,
  "reasoning_effort": "low" | "high",
  "allowed_token_ids": [integer],
  "truncate_prompt_tokens": integer,
  "stream_options": {
    "include_usage": boolean
  }
}
```

**Formato di completamento del testo**

Utilizzate questo formato per una semplice generazione di testo:

```
{
  "prompt": "string",
  "max_tokens": integer,
  "stream": boolean,
  "temperature": float,
  "top_p": float,
  "top_k": integer,
  "logprobs": integer,
  "allowed_token_ids": [integer],
  "truncate_prompt_tokens": integer,
  "stream_options": {
    "include_usage": boolean
  }
}
```

**Formato di completamento della chat multimodale**

Usa questo formato per inserire immagini e testo:

```
{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
      ]
    }
  ],
  "max_tokens": integer,
  "temperature": float,
  "top_p": float,
  "stream": boolean
}
```

**Parametri della richiesta**
+ `messages`(array): Per il formato di completamento della chat. Matrice di oggetti di messaggio con `role` e `content` campi. Il contenuto può essere una stringa di solo testo o un array per input multimodali.
+ `prompt`(stringa): Per il formato di completamento del testo. Il testo di input da cui generare.
+ `max_tokens`(intero): numero massimo di token da generare nella risposta. Intervallo: 1 o superiore.
+ `max_completion_tokens`(intero): alternativa a max\$1tokens per il completamento della chat. Numero massimo di token di completamento da generare.
+ `temperature`(float): controlla la casualità nella generazione. Intervallo: da 0,0 a 2,0 (0,0 = deterministico, 2,0 = casualità massima).
+ `top_p`(float): soglia di campionamento del nucleo. Intervallo: da 1e-10 a 1,0.
+ `top_k`(numero intero): limita la selezione dei token ai primi K token più probabili. Intervallo: -1 o superiore (-1 = nessun limite).
+ `stream`(boolean): Indica se trasmettere la risposta in streaming. Impostato su per lo streaming, `true` `false` per il non streaming.
+ `logprobs`(booleano/intero): per il completamento della chat, usa booleano. Per i completamenti di testo, usa il numero intero per indicare il numero di probabilità di log da restituire. Intervallo: da 1 a 20.
+ `top_logprobs`(numero intero): numero di token per i quali è più probabile che vengano restituite le probabilità di log (solo per il completamento della chat).
+ `reasoning_effort`(stringa): Livello di sforzo di ragionamento. Opzioni: «basso», «alto» (completamenti della chat solo per i modelli personalizzati Nova 2 Lite).
+ `allowed_token_ids`(array): Elenco di token IDs che possono essere generati. Limita l'output ai token specificati.
+ `truncate_prompt_tokens`(numero intero): Tronca il prompt a questo numero di token se supera il limite.
+ `stream_options`(oggetto): opzioni per lo streaming delle risposte. Contiene un valore `include_usage` booleano per includere l'utilizzo del token nelle risposte in streaming.

## Formato della risposta


Il formato della risposta dipende dal metodo di invocazione e dal tipo di richiesta:

**Risposta al completamento della chat (non in streaming)**

Per le richieste sincrone di completamento della chat:

```
{
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm doing well, thank you for asking. How can I help you today?",
        "refusal": null,
        "reasoning": null,
        "reasoning_content": null
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              },
              {
                "token": "Hi",
                "logprob": -1.3190403,
                "bytes": [72, 105]
              }
            ]
          }
        ]
      },
      "finish_reason": "stop",
      "stop_reason": null,
      "token_ids": [9906, 0, 358, 2157, 1049, 11, 1309, 345, 369, 6464, 13]
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "prompt_token_ids": [9906, 0, 358]
}
```

**Risposta di completamento del testo (non in streaming)**

Per le richieste sincrone di completamento del testo:

```
{
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": "Paris, the capital and most populous city of France.",
      "logprobs": {
        "tokens": ["Paris", ",", " the", " capital"],
        "token_logprobs": [-0.31725305, -0.07918124, -0.12345678, -0.23456789],
        "top_logprobs": [
          {
            "Paris": -0.31725305,
            "London": -1.3190403,
            "Rome": -2.1234567
          },
          {
            ",": -0.07918124,
            " is": -1.2345678
          }
        ]
      },
      "finish_reason": "stop",
      "stop_reason": null,
      "prompt_token_ids": [464, 6864, 315, 4881, 374],
      "token_ids": [3915, 11, 279, 6864, 323, 1455, 95551, 3363, 315, 4881, 13]
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 11,
    "total_tokens": 16,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}
```

**Completamento della chat, risposta in streaming**

Per le richieste di completamento della chat in streaming, le risposte vengono inviate come Server-Sent Events (SSE):

```
data: {
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "Hello",
        "refusal": null,
        "reasoning": null,
        "reasoning_content": null
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              }
            ]
          }
        ]
      },
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null,
  "prompt_token_ids": null
}

data: {
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "! I'm"
      },
      "logprobs": null,
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null
}

data: {
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

data: [DONE]
```

**Completamento del testo, risposta in streaming**

Per le richieste di completamento di testi in streaming:

```
data: {
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": "Paris",
      "logprobs": {
        "tokens": ["Paris"],
        "token_logprobs": [-0.31725305],
        "top_logprobs": [
          {
            "Paris": -0.31725305,
            "London": -1.3190403
          }
        ]
      },
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null
}

data: {
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": ", the capital",
      "logprobs": null,
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null
}

data: {
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": "",
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 11,
    "total_tokens": 16
  }
}

data: [DONE]
```

**Spiegazione dei campi di risposta**
+ `id`: identificatore univoco per il completamento
+ `object`: Tipo di oggetto restituito («chat.completion», «text\$1completion», «chat.completion.chunk»)
+ `created`: timestamp Unix di quando è stato creato il completamento
+ `model`: Modello utilizzato per il completamento
+ `choices`: Gamma di scelte di completamento
+ `usage`: informazioni sull'utilizzo dei token, tra cui richiesta, completamento e token totali
+ `logprobs`: Registra le informazioni sulla probabilità dei token (quando richiesto)
+ `finish_reason`: Motivo per cui il modello ha smesso di generare («stop», «length», «content\$1filter»)
+ `delta`: Contenuto incrementale nelle risposte in streaming
+ `reasoning`: Contenuto di ragionamento quando viene utilizzato reasoning\$1effort
+ `token_ids`: Matrice di token IDs per il testo generato

Per una documentazione completa sull'API, consulta [InvokeEndpoint API reference](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) e [InvokeEndpointWithResponseStream API reference](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html).