# API 참조
<a name="nova-sagemaker-inference-api-reference"></a>

SageMaker의 Amazon Nova 모델은 추론에 대해 표준 SageMaker 런타임 API를 사용합니다. 전체 API 설명서는 [Test a deployed model](https://docs.aws.amazon.com//sagemaker/latest/dg/realtime-endpoints-test-endpoints.html)을 참조하세요.

## 엔드포인트 간접 호출
<a name="nova-sagemaker-inference-api-invocation"></a>

SageMaker의 Amazon Nova 모델은 다음과 같은 두 가지 간접 호출 방법을 지원합니다.
+ **동기식 간접 호출**: 실시간 비스트리밍 추론 요청에 대해 [InvokeEndpoint](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) API를 사용합니다.
+ **스트리밍 간접 호출**: 실시간 스트리밍 추론 요청에 대해 [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) API를 사용합니다.

## 요청 형식
<a name="nova-sagemaker-inference-api-request"></a>

Amazon Nova 모델은 다음과 같은 두 가지 요청 형식을 지원합니다.

**채팅 완료 형식**

대화형 상호 작용에 대해 다음 형식을 사용합니다.

```
{
  "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
  }
}
```

**텍스트 완료 형식**

간단한 텍스트 생성에 대해 이 형식을 사용합니다.

```
{
  "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
  }
}
```

**멀티모달 채팅 완료 형식**

이미지 및 텍스트 입력에 대해 이 형식을 사용합니다.

```
{
  "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
}
```

**요청 파라미터**
+ `messages`(배열): 채팅 완료 형식의 경우. `role` 및 `content` 필드가 있는 메시지 객체의 배열. 콘텐츠는 텍스트 전용 문자열 또는 멀티모달 입력 배열일 수 있습니다.
+ `prompt`(문자열): 텍스트 완료 형식의 경우. 생성할 입력 텍스트.
+ `max_tokens`(정수): 응답에서 생성할 최대 토큰 수. 범위: 1 이상.
+ `max_completion_tokens`(정수): 채팅 완료에 대한 max\$1tokens의 대안. 생성할 최대 완료 토큰 수.
+ `temperature`(float): 생성 시 무작위성을 제어합니다. 범위: 0.0\$12.0(0.0 = 결정적, 2.0 = 최대 무작위성).
+ `top_p`(float): Nucleus 샘플링 임계치. 범위: 1e-10\$11.0.
+ `top_k`(정수): 가능성이 가장 큰 상위 K개 토큰으로 토큰 선택을 제한합니다. 범위: -1 이상(-1 = 제한 없음).
+ `stream`(부울): 응답 스트리밍 여부. 스트리밍의 경우 `true`, 비스트리밍의 경우 `false`로 설정합니다.
+ `logprobs`(부울/정수): 채팅 완료의 경우 부울을 사용합니다. 텍스트 완료의 경우 반환할 로그 확률 수에 정수를 사용합니다. 범위: 1\$120.
+ `top_logprobs`(정수): 로그 확률을 반환할 가능성이 가장 큰 토큰 수(채팅 완료만 해당).
+ `reasoning_effort`(문자열): 추론 노력 수준입니다. 옵션: 'low', 'high'(Nova 2 Lite 사용자 지정 모델의 채팅 완료만 해당).
+ `allowed_token_ids`(배열): 생성할 수 있는 토큰 ID 목록. 출력을 지정된 토큰으로 제한합니다.
+ `truncate_prompt_tokens`(정수): 제한을 초과하는 경우 프롬프트를 이 많은 토큰으로 자릅니다.
+ `stream_options`(객체): 스트리밍 응답에 대한 옵션. 스트리밍 응답에서 토큰 사용량을 포함하도록 `include_usage` 부울을 포함합니다.

## 응답 형식
<a name="nova-sagemaker-inference-api-response"></a>

응답 형식은 간접 호출 방법 및 요청 유형에 따라 다릅니다.

**채팅 완료 응답(비스트리밍)**

동기식 채팅 완료 요청의 경우:

```
{
  "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]
}
```

**텍스트 완료 응답(비스트리밍)**

동기식 텍스트 완료 요청의 경우:

```
{
  "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
    }
  }
}
```

**채팅 완료 스트리밍 응답**

스트리밍 채팅 완료 요청의 경우 응답은 서버 전송 이벤트(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]
```

**텍스트 완료 스트리밍 응답**

스트리밍 텍스트 완료 요청의 경우:

```
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]
```

**응답 필드 설명**
+ `id`: 완료에 대한 고유한 식별자
+ `object`: 반환되는 객체 유형('chat.completion', 'text\$1completion', 'chat.completion.chunk')
+ `created`: 완료가 생성된 시간의 Unix 타임스탬프
+ `model`: 완료에 사용되는 모델
+ `choices`: 완료 선택 배열
+ `usage`: 프롬프트, 완료 및 총 토큰을 포함하는 토큰 사용 정보
+ `logprobs`: 토큰에 대한 로그 확률 정보(요청 시)
+ `finish_reason`: 모델 생성이 중지된 이유('stop', 'length', 'content\$1filter')
+ `delta`: 스트리밍 응답의 증분 콘텐츠
+ `reasoning`: reasoning\$1effort를 사용하는 경우 추론 콘텐츠
+ `token_ids`: 생성된 텍스트에 대한 토큰 ID 배열

전체 API 설명서는 [InvokeEndpoint API 참조](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) 및 [InvokeEndpointWithResponseStream API 참조](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html)를 참조하세요.