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à.
# Schema di richiesta e risposta
Lo schema di richiesta è quasi identico tra l'API Invoke e l'API Converse. La differenza principale è il modo in cui i dati binari (immagini, video, audio) vengono codificati: l'API Converse utilizza array binari mentre l'API Invoke utilizza stringhe con codifica Base64.
## Struttura completa delle richieste
Di seguito viene illustrata la struttura completa delle richieste per i modelli Amazon Nova. Tutti i campi sono facoltativi a meno che non siano contrassegnati come obbligatori:
```
{
"system": [
{
"text": "string"
}
],
"messages": [ // Required
{
"role": "user", // Required - first turn must be user
"content": [ // Required
{
"text": "string"
},
{
"image": {
"format": "jpeg" | "png" | "gif" | "webp", // Required
"source": { // Required
"bytes": image // Binary array (Converse) or Base64 string (Invoke)
}
}
},
{
"video": {
"format": "mkv" | "mov" | "mp4" | "webm" | "three_gp" | "flv" | "mpeg" | "mpg" | "wmv",
"source": {
// Option 1: S3 location
"s3Location": {
"uri": "string", // e.g., s3://my-bucket/object-key
"bucketOwner": "string" // Optional, e.g., "123456789012"
},
// Option 2: File bytes
"bytes": video // Binary array (Converse) or Base64 string (Invoke)
}
}
},
{
"audio": { // Nova 2 Omni and Sonic only
"format": "mp3" | "opus" | "wav" | "aac" | "flac" | "mp4" | "ogg" | "mkv",
"source": {
// Option 1: S3 location
"s3Location": {
"uri": "string",
"bucketOwner": "string" // Optional
},
// Option 2: File bytes
"bytes": audio // Binary array (Converse) or Base64 string (Invoke)
}
}
}
]
},
{
"role": "assistant",
"content": [
{
"text": "string" // For prefilling assistant response
}
]
}
],
"inferenceConfig": { // All optional
"maxTokens": int, // 1-5000, default: dynamic
"temperature": float, // 0.00001-1, default: 0.7
"topP": float, // 0-1, default: 0.9
"topK": int, // 0-128, default: not used
"stopSequences": ["string"],
"reasoningConfig": { // Nova 2 Lite and Sonic only
"type": "enabled" | "disabled", // default: "disabled"
"maxReasoningEffort": "low" | "medium" | "high"
}
},
"toolConfig": { // Optional
"tools": [
{
"toolSpec": {
"name": "string", // Max 64 characters
"description": "string",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"arg1": {
"type": "string",
"description": "string"
}
},
"required": ["string"]
}
}
}
}
],
"toolChoice": { // Choose one option
"auto": {},
"any": {},
"tool": {
"name": "string"
}
}
}
}
```
Parametri chiave della richiesta:
+ `system`: prompt di sistema che fornisce contesto e istruzioni
+ `messages`: La serie di conversazioni varia in base al ruolo (utente o assistente) e al contenuto
+ `inferenceConfig`: controlla il comportamento di output del modello (temperatura, token e così via).
+ `toolConfig`: specifiche degli strumenti per la chiamata di funzioni
**Nota**
Quando si utilizza l'API Converse, è necessario inserire `reasoningConfig` i parametri `topK` and `additionalModelRequestFields` anziché`inferenceConfig`.
Le seguenti sezioni forniscono spiegazioni dettagliate di ciascun parametro di richiesta:
### sistema
`system` (facoltativo): il prompt di sistema per la richiesta. Un prompt di sistema fornisce contesto e istruzioni ad Amazon Nova, ad esempio per specificare un obiettivo o un ruolo particolare.
### messages
`messages`— (Obbligatorio) L'array di messaggi di input contenente i turni di conversazione.
+ `role`— (Obbligatorio) Il ruolo del turno di conversazione. I valori validi sono `user` e `assistant`. Il primo messaggio deve sempre utilizzare il `user` ruolo.
+ `content`— (Obbligatorio) Una serie di blocchi di contenuto. Ogni blocco specifica un tipo di contenuto (`text`, `image``video`, o`audio`):
+ `text`— Contenuto testuale per il turno di conversazione. Se combinato con un'immagine o un video, interpretato come testo di accompagnamento.
+ `image`— (Non supportato per Nova 2 Lite) Contenuto dell'immagine con:
+ `format`— (Obbligatorio) Formato dell'immagine: `jpeg``png`,`webp`, o `gif`
+ `source.bytes`— (Obbligatorio) Dati di immagine come array binario (Converse API) o stringa Base64 (Invoke API)
+ `video`— (Non supportato per Nova 2 Lite) Contenuti video con:
+ `format`— (Obbligatorio) Formato video: `mkv` `mov``mp4`,`webm`,`three_gp`,,`flv`,`mpeg`,`mpg`, o `wmv`
+ `source`— (Obbligatorio) Sorgente video tramite URI S3 (`s3Location.uri`e opzionale`bucketOwner`) o file byte () `bytes`
+ `audio`— (Amazon Nova Sonic e solo) Contenuti audio con:
+ `format`— (Obbligatorio) Formato audio: `mp3``opus`,`wav`,`aac`,`flac`,, `mp4``ogg`, o `mkv`
+ `source`— (Obbligatorio) Sorgente audio tramite URI S3 o byte di file
### inferenceConfig
`inferenceConfig`— (Opzionale) Parametri di configurazione che controllano la generazione dell'output del modello.
+ `maxTokens`— (Facoltativo) Numero massimo di token da generare prima dell'arresto. I modelli Amazon Nova potrebbero interrompersi prima di raggiungere questo limite. Il valore massimo è 5.000. Se non specificato, utilizza un valore predefinito dinamico basato sul contesto della richiesta.
+ `temperature`— (Facoltativo) Casualità nelle risposte. Intervallo valido: 0,00001-1 (predefinito: 0,7). I valori più bassi producono un output più deterministico.
+ `topP`— (Facoltativo) Soglia di campionamento del nucleo. Amazon Nova campiona token la cui probabilità cumulativa raggiunge. `topP` Intervallo valido: 0-1 (impostazione predefinita: 0,9). Regola una delle due `temperature` o `topP` non entrambe.
+ `topK`— (Facoltativo) Esamina solo i migliori token K. Rimuove le risposte a bassa probabilità. Intervallo valido: 0-128 (impostazione predefinita: non utilizzato).
**Nota**
Per l'API Converse, passa. `topK` `additionalModelRequestFields`
+ `stopSequences`— (Facoltativo) Matrice di stringhe che interrompono la generazione quando vengono rilevate.
+ `reasoningConfig`— (Solo Amazon Nova Sonic) Configurazione del ragionamento:
+ `type`— (Facoltativo) `enabled` o `disabled` (impostazione predefinita:) `disabled`
+ `maxReasoningEffort`— Sforzo computazionale:`low`,`medium`, o`high`. Con `low` e`medium`, il ragionamento scorre in modo incrementale; `high` restituisce il ragionamento in una parte finale.
**Nota**
Per l'API Converse, passa. `reasoningConfig` `additionalModelRequestFields`
### toolConfig
`toolConfig`— (Facoltativo) Configurazione dello strumento secondo [ToolConfiguration lo schema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html).
+ `tools`— Serie di specifiche degli utensili con `name` `description` e `inputSchema`
+ `toolChoice`— (Opzionale) Controlla la selezione degli utensili:
+ `auto`— Il modello decide se e quali strumenti utilizzare
+ `any`— Il modello deve utilizzare almeno un utensile
+ `tool`— Il modello deve utilizzare l'utensile specificato per nome
## Struttura di risposta completa
Di seguito viene illustrata la struttura di risposta completa per i modelli Amazon Nova:
```
{
"ResponseMetadata": {
"RequestId": "string",
"HTTPStatusCode": int,
"HTTPHeaders": {
"date": "string",
"content-type": "application/json",
"content-length": "string",
"connection": "keep-alive",
"x-amzn-requestid": "string"
},
"RetryAttempts": 0
},
"output": {
"message": {
"role": "assistant",
"content": [
{
"reasoningContent": { // Optional - if reasoning enabled
"reasoningText": {
"text": "[REDACTED]"
}
}
},
{
"toolUse": { // Optional - if tool called
"toolUseId": "string",
"name": "string",
"input": {} // Tool-specific arguments
}
},
{
"text": "string" // Optional - text response
},
{
"image": { // Optional - Nova 2 Omni only
"format": "png",
"source": {
"bytes": image // Binary array (Converse) or Base64 string (Invoke)
}
}
}
]
}
},
"stopReason": "string", // See stop reasons below
"usage": {
"inputTokens": int,
"outputTokens": int,
"totalTokens": int
},
"metrics": {
"latencyMs": int
}
}
```
Motivi dello stop:
+ `end_turn`: Fine naturale della risposta
+ `max_tokens`: Raggiunto il limite MaxTokens
+ `content_filtered`: Politica sui contenuti violata
+ `malformed_model_output`: output del modello non valido
+ `malformed_tool_use`: output di utilizzo dello strumento non valido
+ `service_unavailable`: servizio utensili integrato irraggiungibile
+ `invalid_query`: Interrogazione non valida sullo strumento integrato
+ `max_tool_invocations`: Tentativi dello strumento esauriti
Le seguenti sezioni forniscono spiegazioni dettagliate di ogni campo di risposta:
### output
`output`— (Obbligatorio) Contiene il messaggio di risposta del modello.
+ `message`— (Obbligatorio) Il messaggio di risposta dell'assistente con ruolo e array di contenuti.
+ `content`— (Obbligatorio) Matrice di blocchi di contenuto che può includere:
+ `reasoningContent`— (Facoltativo) Restituito se il ragionamento era abilitato. Contiene il testo del ragionamento, che sarà sempre presente `[REDACTED]` nella risposta.
+ `toolUse`— (Facoltativo) Restituito se è stato chiamato uno strumento. Contiene l'ID di utilizzo dello strumento, il nome e gli argomenti di input.
+ `text`— (Facoltativo) Restituito se il modello ha risposto con contenuto testuale.
+ `image`— (Facoltativo, solo) Restituito se il modello ha generato un'immagine. Il formato sarà sempre PNG.
### Interrompi Reason
`stopReason`— (Obbligatorio) Indica il motivo per cui il modello ha smesso di generare output:
+ `end_turn`— Fine naturale della risposta raggiunta
+ `max_tokens`— Raggiunto il limite MaxTokens o il limite di output massimo del modello
+ `content_filtered`— Output violato AWS la politica di intelligenza artificiale responsabile
+ `malformed_model_output`— Il modello ha prodotto un output non valido
+ `malformed_tool_use`— Il modello ha prodotto un output di utilizzo dell'utensile non valido
+ `service_unavailable`— Il servizio utensili integrato non è stato raggiungibile
+ `invalid_query`— La query sullo strumento integrato non era valida
+ `max_tool_invocations`— Lo strumento integrato non ha prodotto risultati validi dopo nuovi tentativi
### utilizzo
`usage`— (Obbligatorio) Informazioni sull'utilizzo del token:
+ `inputTokens`— Token totali ingeriti dal modello
+ `outputTokens`— Numero di token generati
+ `totalTokens`— Somma dei token di input e output
### metriche
`metrics`— Metriche prestazionali (obbligatorie):
+ `latencyMs`— Tempo totale di completamento dell'inferenza in millisecondi