Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Skema permintaan dan respons
Skema permintaan hampir identik antara Invoke API dan Converse API. Perbedaan utama adalah bagaimana data biner (gambar, video, audio) dikodekan: Converse API menggunakan array biner sedangkan Invoke API menggunakan string yang dikodekan Base64.
## Struktur permintaan lengkap
Berikut ini menunjukkan struktur permintaan lengkap untuk model Amazon Nova. Semua bidang bersifat opsional kecuali ditandai sebagai wajib:
```
{
"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"
}
}
}
}
```
Parameter permintaan kunci:
+ `system`: Prompt sistem memberikan konteks dan instruksi
+ `messages`: Array percakapan berubah dengan peran (pengguna atau asisten) dan konten
+ `inferenceConfig`: Mengontrol perilaku keluaran model (suhu, token, dan sebagainya.)
+ `toolConfig`: Spesifikasi alat untuk pemanggilan fungsi
**catatan**
Saat menggunakan Converse API, `reasoningConfig` parameter `topK` and harus ditempatkan `additionalModelRequestFields` sebagai ganti. `inferenceConfig`
Bagian berikut memberikan penjelasan rinci dari setiap parameter permintaan:
### sistem
`system`— (Opsional) Prompt sistem untuk permintaan. Prompt sistem memberikan konteks dan instruksi ke Amazon Nova, seperti menentukan tujuan atau peran tertentu.
### pesan
`messages`— (Wajib) Array pesan masukan yang berisi percakapan berubah.
+ `role`— (Wajib) Peran percakapan berubah. Nilai yang valid adalah `user` dan `assistant`. Pesan pertama harus selalu menggunakan `user` peran.
+ `content`— (Diperlukan) Sebuah array blok konten. Setiap blok menentukan jenis konten (`text`,, `image``video`, atau`audio`):
+ `text`— Konten teks untuk giliran percakapan. Jika dikombinasikan dengan gambar atau video, ditafsirkan sebagai teks yang menyertainya.
+ `image`— (Tidak didukung untuk Nova 2 Lite) Konten gambar dengan:
+ `format`- (Diperlukan) Format gambar:`jpeg`,`png`,`webp`, atau `gif`
+ `source.bytes`— (Diperlukan) Data gambar sebagai array biner (Converse API) atau string Base64 (Invoke API)
+ `video`— (Tidak didukung untuk Nova 2 Lite) Konten video dengan:
+ `format`— (Diperlukan) Format video: `mkv``mov`,`mp4`,`webm`,`three_gp`,`flv`,`mpeg`,`mpg`, atau `wmv`
+ `source`— (Diperlukan) Sumber video melalui URI S3 (`s3Location.uri`dan opsional`bucketOwner`) atau byte file () `bytes`
+ `audio`— (Amazon Nova Sonic dan hanya) Konten audio dengan:
+ `format`— (Diperlukan) Format audio: `mp3``opus`,`wav`,`aac`,`flac`,`mp4`,`ogg`, atau `mkv`
+ `source`- (Diperlukan) Sumber audio melalui URI S3 atau byte file
### InferensiConfig
`inferenceConfig`- (Opsional) Parameter konfigurasi yang mengendalikan generasi keluaran model.
+ `maxTokens`— (Opsional) Token maksimum untuk dihasilkan sebelum berhenti. Model Amazon Nova dapat berhenti sebelum mencapai batas ini. Nilai maksimum adalah 5.000. Jika tidak ditentukan, menggunakan default dinamis berdasarkan konteks permintaan.
+ `temperature`— (Opsional) Keacakan dalam tanggapan. Rentang yang valid: 0,00001-1 (default: 0,7). Nilai yang lebih rendah menghasilkan output yang lebih deterministik.
+ `topP`— (Opsional) Ambang pengambilan sampel nukleus. Amazon Nova sampel dari token yang probabilitas kumulatifnya mencapai. `topP` Rentang yang valid: 0-1 (default: 0.9). Sesuaikan salah satu `temperature` atau`topP`, tidak keduanya.
+ `topK`— (Opsional) Sampel dari token K teratas saja. Menghapus respons probabilitas rendah. Rentang yang valid: 0-128 (default: tidak digunakan).
**catatan**
Untuk Converse API, teruskan`topK`. `additionalModelRequestFields`
+ `stopSequences`— (Opsional) Array string yang menghentikan pembuatan saat ditemui.
+ `reasoningConfig`— (Amazon Nova Sonic dan hanya) Konfigurasi penalaran:
+ `type`— (Opsional) `enabled` atau `disabled` (default:`disabled`)
+ `maxReasoningEffort`— Upaya komputasi:`low`,`medium`, atau. `high` Dengan `low` dan`medium`, aliran penalaran secara bertahap; `high` menghasilkan penalaran dalam potongan terakhir.
**catatan**
Untuk Converse API, teruskan`reasoningConfig`. `additionalModelRequestFields`
### ToolConfig
`toolConfig`- (Opsional) Konfigurasi alat mengikuti [ToolConfiguration skema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html).
+ `tools`— Array spesifikasi alat dengan`name`, `description` dan `inputSchema`
+ `toolChoice`— (Opsional) Kontrol pemilihan alat:
+ `auto`— Model memutuskan apakah dan alat mana yang akan digunakan
+ `any`— Model harus menggunakan setidaknya satu alat
+ `tool`— Model harus menggunakan alat yang ditentukan dengan nama
## Struktur respons lengkap
Berikut ini menunjukkan struktur respons lengkap untuk model 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
}
}
```
Hentikan alasan:
+ `end_turn`: Akhir respons alami
+ `max_tokens`: Mencapai batas MaxTokens
+ `content_filtered`: Kebijakan konten yang dilanggar
+ `malformed_model_output`: Output model tidak valid
+ `malformed_tool_use`: Output penggunaan alat tidak valid
+ `service_unavailable`: Layanan alat bawaan tidak dapat dijangkau
+ `invalid_query`: Kueri tidak valid ke alat bawaan
+ `max_tool_invocations`: Alat coba lagi habis
Bagian berikut memberikan penjelasan rinci dari setiap bidang respons:
### output
`output`— (Wajib) Berisi pesan respons model.
+ `message`— (Diperlukan) Pesan respons asisten dengan peran dan array konten.
+ `content`— (Diperlukan) Array blok konten yang dapat mencakup:
+ `reasoningContent`— (Opsional) Dikembalikan jika penalaran diaktifkan. Berisi teks penalaran, yang akan selalu menjadi `[REDACTED]` respons.
+ `toolUse`— (Opsional) Dikembalikan jika alat dipanggil. Berisi alat menggunakan ID, nama dan argumen masukan.
+ `text`— (Opsional) Dikembalikan jika model merespons dengan konten teks.
+ `image`— (Opsional, hanya) Dikembalikan jika model menghasilkan gambar. Format akan selalu PNG.
### StopReason
`stopReason`— (Wajib) Menunjukkan mengapa model berhenti menghasilkan output:
+ `end_turn`— Akhir respons alami tercapai
+ `max_tokens`— Mencapai batas MaxTokens atau batas output maksimum model
+ `content_filtered`— Output melanggar kebijakan AI yang Bertanggung AWS Jawab
+ `malformed_model_output`— Model menghasilkan output tidak valid
+ `malformed_tool_use`— Model menghasilkan alat yang tidak valid menggunakan output
+ `service_unavailable`— Layanan alat bawaan tidak dapat dihubungi
+ `invalid_query`— Kueri ke alat bawaan tidak valid
+ `max_tool_invocations`— Alat bawaan tidak menghasilkan hasil yang valid setelah mencoba ulang
### pemakaian
`usage`— (Diperlukan) Informasi penggunaan Token:
+ `inputTokens`— Total token yang dicerna oleh model
+ `outputTokens`— Jumlah token yang dihasilkan
+ `totalTokens`— Jumlah token input dan output
### metrik
`metrics`— (Diperlukan) Metrik kinerja:
+ `latencyMs`— Total waktu penyelesaian inferensi dalam milidetik