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

# Create a message

Anthropic Messages API 형식을 사용하여 메시지를 생성합니다. 텍스트, 이미지, PDF, 도구 및 확장 사고를 지원합니다.

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer 토큰. API 키를 Authorization 헤더의 Bearer 토큰으로 사용하세요.

  Format: `Bearer <SUNRA_KEY>`
</ParamField>

## 요청

이 엔드포인트는 JSON 객체를 받습니다.

<ParamField body="model" type="string" required>
  프롬프트를 완성할 모델. 사용 가능한 모델은 [sunra.ai/models](https://sunra.ai/models)에서 확인하세요.
</ParamField>

<ParamField body="messages" type="object[]" required>
  입력 메시지. 각 입력 메시지에는 `role`과 `content`가 있습니다.

  <Expandable title="속성">
    <ParamField body="role" type="string" required>
      메시지 작성자의 역할. 지원되는 값: `user`, `assistant`.
    </ParamField>

    <ParamField body="content" type="string | object[]" required>
      메시지의 내용. 단일 문자열 또는 콘텐츠 블록 배열을 지정할 수 있습니다.

      <Expandable title="콘텐츠 블록 유형">
        <ParamField body="type" type="string" required>
          콘텐츠 블록의 유형. 지원되는 값: `text`, `image`, `tool_use`, `tool_result`.
        </ParamField>

        <ParamField body="text" type="string">
          텍스트 콘텐츠. type이 `text`인 경우 사용됩니다.
        </ParamField>

        <ParamField body="source" type="object">
          이미지 소스. type이 `image`인 경우 사용됩니다.

          <Expandable title="속성">
            <ParamField body="type" type="string" required>
              소스 유형. 지원되는 값: `base64`, `url`.
            </ParamField>

            <ParamField body="media_type" type="string" required>
              이미지의 미디어 유형. 예: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
            </ParamField>

            <ParamField body="data" type="string">
              Base64로 인코딩된 이미지 데이터. 소스 유형이 `base64`인 경우 필수입니다.
            </ParamField>

            <ParamField body="url" type="string">
              이미지 URL. 소스 유형이 `url`인 경우 필수입니다.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  중단 전에 생성할 최대 토큰 수. 모델이 이 최대값에 도달하기 전에 중단할 수 있습니다.
</ParamField>

<ParamField body="system" type="string | object[]">
  시스템 프롬프트. 모델에 컨텍스트와 지침을 제공하는 방법입니다. 문자열 또는 콘텐츠 블록 배열을 지정할 수 있습니다.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  서버 전송 이벤트(SSE)를 사용하여 응답을 점진적으로 스트리밍할지 여부.
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  응답에 주입되는 무작위성의 양. 0.0에서 1.0 범위. 분석/객관식 작업에는 0.0에 가까운 `temperature`를, 창의적이고 생성적인 작업에는 1.0에 가까운 값을 사용하세요.
</ParamField>

<ParamField body="top_p" type="number">
  핵 샘플링을 사용합니다. 핵 샘플링에서는 확률이 감소하는 순서로 각 후속 토큰의 모든 옵션에 대한 누적 분포를 계산하고 `top_p`로 지정된 특정 확률에 도달하면 중단합니다.
</ParamField>

<ParamField body="top_k" type="integer">
  각 후속 토큰에 대해 상위 K개의 옵션에서만 샘플링합니다. 확률이 낮은 "롱테일" 응답을 제거하는 데 사용됩니다. 고급 사용 사례에만 권장됩니다.
</ParamField>

<ParamField body="stop_sequences" type="string[]">
  모델의 생성을 중단시키는 사용자 정의 텍스트 시퀀스. 반환된 텍스트에는 중단 시퀀스가 포함되지 않습니다.
</ParamField>

<ParamField body="tools" type="object[]">
  모델이 사용할 수 있는 도구 정의.

  <Expandable title="속성">
    <ParamField body="name" type="string" required>
      도구의 이름.
    </ParamField>

    <ParamField body="description" type="string">
      이 도구가 수행하는 작업에 대한 설명.
    </ParamField>

    <ParamField body="input_schema" type="object" required>
      이 도구의 입력에 대한 JSON 스키마. 도구가 허용하는 `input`의 형태를 정의합니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="object">
  모델이 제공된 도구를 어떻게 사용할지 지정합니다.

  <Expandable title="속성">
    <ParamField body="type" type="string" required>
      지원되는 값: `auto`(기본값, 모델이 결정), `any`(모델이 반드시 도구를 사용해야 함), `tool`(모델이 특정 도구를 사용해야 함).
    </ParamField>

    <ParamField body="name" type="string">
      사용할 도구의 이름. type이 `tool`인 경우 필수입니다.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  요청에 대한 메타데이터를 설명하는 객체.

  <Expandable title="속성">
    <ParamField body="user_id" type="string">
      요청과 연결된 사용자의 외부 식별자.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="thinking" type="object">
  확장 사고 구성. 활성화하면 모델이 응답하기 전에 사고합니다.

  <Expandable title="속성">
    <ParamField body="type" type="string" required>
      반드시 `enabled`여야 합니다.
    </ParamField>

    <ParamField body="budget_tokens" type="integer" required>
      사고에 사용할 최대 토큰 수. 1024 이상이어야 합니다.
    </ParamField>
  </Expandable>
</ParamField>

## 응답

메시지 성공 응답.

<ResponseField name="id" type="string">
  고유 메시지 식별자. 예: `msg_01XFDUDYJgAACzvnptvVoYEL`.
</ResponseField>

<ResponseField name="type" type="string">
  객체 유형. 항상 `message`.
</ResponseField>

<ResponseField name="role" type="string">
  생성된 메시지의 대화 역할. 항상 `assistant`.
</ResponseField>

<ResponseField name="content" type="object[]">
  모델이 생성한 콘텐츠. 콘텐츠 블록의 배열입니다.

  <Expandable title="속성">
    <ResponseField name="type" type="string">
      콘텐츠 블록의 유형. `text`, `tool_use`, 또는 `thinking`일 수 있습니다.
    </ResponseField>

    <ResponseField name="text" type="string">
      생성된 텍스트. type이 `text`인 경우 존재합니다.
    </ResponseField>

    <ResponseField name="id" type="string">
      도구 사용 블록의 ID. type이 `tool_use`인 경우 존재합니다.
    </ResponseField>

    <ResponseField name="name" type="string">
      도구의 이름. type이 `tool_use`인 경우 존재합니다.
    </ResponseField>

    <ResponseField name="input" type="object">
      도구에 대한 입력. type이 `tool_use`인 경우 존재합니다.
    </ResponseField>

    <ResponseField name="thinking" type="string">
      사고 내용. type이 `thinking`인 경우 존재합니다.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  요청을 처리한 모델.
</ResponseField>

<ResponseField name="stop_reason" type="string | null">
  모델이 중단한 이유. `end_turn`(모델이 자연스러운 중단점에 도달), `max_tokens`(`max_tokens` 또는 모델의 최대값 초과), `stop_sequence`(사용자 정의 중단 시퀀스 중 하나가 생성됨), 또는 `tool_use`(모델이 하나 이상의 도구를 호출함)일 수 있습니다.
</ResponseField>

<ResponseField name="stop_sequence" type="string | null">
  생성된 사용자 정의 중단 시퀀스(해당하는 경우).
</ResponseField>

<ResponseField name="usage" type="object">
  청구 및 속도 제한 사용량. 세 가지 입력 버킷은 상호 배타적입니다 — [토큰 사용량](/ko/llm/token-usage)을 참고하세요.

  <Expandable title="속성">
    <ResponseField name="input_tokens" type="integer">
      사용된 신규 입력 토큰 수. 두 캐시 버킷은 모두 제외합니다.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      사용된 출력 토큰 수.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      모든 입력 버킷과 `output_tokens`의 합. 스트리밍 응답에서는 생략됩니다.
    </ResponseField>

    <ResponseField name="cache_creation_input_tokens" type="integer">
      캐시 항목을 생성하는 데 사용된 입력 토큰 수.
    </ResponseField>

    <ResponseField name="cache_read_input_tokens" type="integer">
      캐시에서 읽은 입력 토큰 수.
    </ResponseField>

    <ResponseField name="sunra_usage_semantics" type="string | null">
      Sunra가 이 응답을 정규화한 경우 `anthropic.exclusive.v1`로 존재합니다. 숫자로 규약을 추론하지 말고 이 값을 검증하세요. [토큰 사용량](/ko/llm/token-usage)을 참고하세요.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/messages \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-sonnet-4-20250514",
      "max_tokens": 1024,
      "messages": [
        {
          "role": "user",
          "content": "Hello, how are you?"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-llm.sunra.ai/v1/messages",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "anthropic/claude-sonnet-4-20250514",
          "max_tokens": 1024,
          "messages": [
              {"role": "user", "content": "Hello, how are you?"}
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "anthropic/claude-sonnet-4-20250514",
      max_tokens: 1024,
      messages: [
        { role: "user", content: "Hello, how are you?" }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ],
    "model": "anthropic/claude-sonnet-4-20250514",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 12,
      "output_tokens": 19,
      "total_tokens": 31,
      "sunra_usage_semantics": "anthropic.exclusive.v1"
    }
  }
  ```
</ResponseExample>