다음을 통해 공유

Azure OpenAI 서비스 REST API 참조

  • 아티클

이 문서에서는 Azure OpenAI에 대한 유추 REST API 엔드포인트에 대한 세부 정보를 제공합니다.

인증

Azure OpenAI는 두 가지 인증 방법을 제공합니다. API 키 또는 Microsoft Entra ID를 사용할 수 있습니다.

  • API 키 인증: 이 인증 형식의 경우 모든 API 요청은 api-key HTTP 헤더에 API 키를 포함해야 합니다. 빠른 시작은 이러한 형식의 인증으로 전화를 거는 방법에 대한 지침을 제공합니다.

  • Microsoft Entra ID 인증: Microsoft Entra 토큰을 사용하여 API 호출을 인증할 수 있습니다. 인증 토큰은 요청에 Authorization 헤더로 포함됩니다. 제공된 토큰은 Bearer가 앞에 와야 합니다(예: Bearer YOUR_AUTH_TOKEN). Microsoft Entra ID로 인증하는 방법 가이드를 읽을 수 있습니다.

REST API 버전 관리

서비스 API는 api-version 쿼리 매개 변수를 사용하여 버전이 지정됩니다. 모든 버전은 YYYY-MM-DD 날짜 구조를 따릅니다. 예시:

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01

완성

완료 작업을 통해 모델은 제공된 프롬프트를 기반으로 하나 이상의 예측 완료를 생성합니다. 서비스는 또한 각 위치에서 대체 토큰의 확률을 반환할 수 있습니다.

완료 만들기

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required 모델을 배포할 때 선택한 배포 이름입니다.
api-version string Required 이 작업에 사용할 API 버전입니다. YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
prompt 문자열 또는 배열 선택 사항 <\|endoftext\|> 문자열 또는 문자열 배열로 인코딩된 완성을 생성하라는 프롬프트 또는 여러 프롬프트입니다. <\|endoftext\|>는 학습 중에 모델이 보는 문서 구분 기호이므로, 프롬프트가 지정되지 않은 경우 모델은 새 문서의 시작 부분에서 생성되는 것처럼 생성됩니다.
max_tokens 정수 선택 사항 16 완료 시 생성할 최대 토큰 수입니다. 프롬프트의 토큰 수와 max_tokens는 모델의 컨텍스트 길이를 초과할 수 없습니다. 대부분의 모델에는 컨텍스트 길이가 2048인 토큰이 있습니다(4096을 지원하는 최신 모델 제외).
temperature number 선택 사항 1 사용할 샘플링 온도(0에서 2 사이)입니다. 값이 클수록 모델이 더 많은 위험을 감수함을 의미합니다. 더 창의적인 애플리케이션의 경우 0.9를 시도하고 답변이 잘 정의된 애플리케이션의 경우 0(argmax sampling)을 시도합니다. 일반적으로 이를 변경하거나 top_p를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다.
top_p number 선택 사항 1 모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 질량을 구성하는 토큰만 고려됨을 의미합니다. 일반적으로 이를 변경하거나 온도를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다.
logit_bias map 선택 사항 null 완료 시 지정된 토큰이 나타날 가능성을 수정합니다. 토큰(GPT 토크나이저에서 토큰 ID로 지정)을 -100에서 100 사이의 관련 바이어스 값에 매핑하는 json 개체를 허용합니다. 이 토크나이저 도구(GPT-2 및 GPT-3 모두에서 작동)를 사용하여 텍스트를 토큰 ID로 변환할 수 있습니다. 수학적으로, 바이어스는 샘플링 전에 모델에 의해 생성된 로짓에 추가됩니다. 정확한 효과는 모델마다 다르지만, -1과 1 사이의 값은 선택 가능성을 낮추거나 높여야 합니다. -100이나 100 같은 값은 관련 토큰을 금지하거나 독점적으로 선택해야 합니다. 예를 들어 {"50256": -100}을 전달하여 <|endoftext|> 토큰이 생성되지 않도록 할 수 있습니다.
user string 선택 사항 최종 사용자를 나타내는 고유 식별자로, 남용을 모니터링하고 감지하는 데 도움이 됩니다.
n 정수 선택 사항 1 각 프롬프트에 대해 생성할 완료 수입니다. 참고: 이 매개 변수는 많은 완료를 생성하므로 토큰 할당량을 빠르게 소모할 수 있습니다. 신중하게 사용하고 max_tokens 및 중지에 대한 적절한 설정이 있는지 확인합니다.
stream 부울 값 선택 사항 False 부분 진행률을 다시 스트리밍할지 여부를 나타냅니다. 설정된 경우 사용할 수 있게 되면 토큰은 데이터 전용 서버 전송 이벤트로 전송되고 스트림은 data: [DONE] 메시지로 종료됩니다.
logprobs 정수 선택 사항 null 가장 가능성이 높은 토큰과 선택한 토큰에 대한 로그 확률을 포함합니다. 예를 들어 logprobs가 10이면 API는 가장 가능성이 높은 토큰 10개의 목록을 반환합니다. API는 항상 샘플링된 토큰의 logprob를 반환하므로 응답에 최대 logprobs+1개의 요소가 있을 수 있습니다. 이 매개 변수는 gpt-35-turbo와 함께 사용할 수 없습니다.
suffix string 선택 사항 null 삽입된 텍스트가 완료된 뒤에 오는 접미사입니다.
echo 부울 값 선택 사항 False 완료와 함께 프롬프트를 다시 에코합니다. 이 매개 변수는 gpt-35-turbo와 함께 사용할 수 없습니다.
stop 문자열 또는 배열 선택 사항 null API가 추가 토큰 생성을 중지하는 최대 4개의 시퀀스입니다. 반환된 텍스트에는 중지 시퀀스가 포함되지 않습니다. 비전이 포함된 GPT-4 Turbo의 경우 시퀀스가 최대 2개 지원됩니다.
presence_penalty number 선택 사항 0 -2.0~2.0 사이의 숫자 양수 값은 지금까지 텍스트에 나타나는지 여부에 따라 새 토큰에 페널티를 부여하여 모델이 새 항목에 대해 이야기할 가능성을 높입니다.
frequency_penalty number 선택 사항 0 -2.0~2.0 사이의 숫자 양수 값은 지금까지 텍스트의 기존 빈도를 기반으로 새 토큰에 불이익을 주어 모델이 동일한 줄을 그대로 반복할 가능성을 줄입니다.
best_of 정수 선택 사항 1 서버 쪽에서 best_of 완료를 생성하고 "최상"(토큰당 로그 확률이 가장 낮은 것)을 반환합니다. 결과를 스트리밍할 수 없습니다. n과 함께 사용하면 best_of는 후보 완료 횟수를 제어하고 n은 반환할 횟수를 지정합니다. best_of는 n보다 커야 합니다. 참고: 이 매개 변수는 많은 완료를 생성하므로 토큰 할당량을 빠르게 소모할 수 있습니다. 신중하게 사용하고 max_tokens 및 중지에 대한 적절한 설정이 있는지 확인합니다. 이 매개 변수는 gpt-35-turbo와 함께 사용할 수 없습니다.

예제 요청

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

예제 응답

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

예제 응답에서 finish_reason은 stop과 같습니다. finish_reason이 content_filter와 같으면 콘텐츠 필터링 가이드를 참조하여 이 문제가 발생하는 이유를 이해하세요.

포함

기계 학습 모델 및 기타 알고리즘에서 쉽게 사용할 수 있는 지정된 입력의 벡터 표현을 가져옵니다.

참고 항목

OpenAI는 현재 text-embedding-ada-002을 사용하여 더 많은 수의 배열 입력을 허용합니다. Azure OpenAI는 현재 text-embedding-ada-002 (Version 2)에 대해 최대 16개의 입력 배열을 지원합니다. 둘 다 이 모델에 대해 8191 미만으로 유지하려면 API 요청당 최대 입력 토큰 제한이 필요합니다.

포함 만들기

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required 모델 배포의 이름입니다. 전화를 걸려면 먼저 모델을 배포해야 합니다.
api-version string Required 이 작업에 사용할 API 버전입니다. YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
input 문자열 또는 배열 예 해당 없음 배열 또는 문자열로 인코딩된 포함 항목을 가져올 텍스트를 입력합니다. 입력 토큰의 수는 사용 중인 모델에 따라 다릅니다. text-embedding-ada-002 (Version 2)만 배열 입력을 지원합니다.
user string 아니요 Null 최종 사용자를 나타내는 고유 식별자입니다. 이렇게 하면 Azure OpenAI가 남용을 모니터링하고 검색하는 데 도움이 됩니다. PII 식별자를 전달하지 말고 GUID와 같은 의사 익명 값을 대신 사용
encoding_format string 아니요 float 포함을 반환할 형식입니다. float 또는 base64 중 하나일 수 있습니다. 기본값은 float입니다.

[2024-03-01-preview에 추가됨].
dimensions 정수 아니요 결과 출력 포함에 있어야 하는 차원의 수입니다. text-embedding-3 이상 모델에서만 지원됩니다.

[2024-03-01-preview에 추가됨]

예제 요청

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

예제 응답

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

채팅 완료

GPT-35-Turbo 및 GPT-4 모델을 사용하여 채팅 메시지 완성을 만듭니다.

채팅 완료 만들기

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required 모델 배포의 이름입니다. 전화를 걸려면 먼저 모델을 배포해야 합니다.
api-version string Required 이 작업에 사용할 API 버전입니다. YYYY-MM-DD 또는 YYYY-MM-DD-미리 보기 형식을 따릅니다.

지원되는 버전

Important

functions 및 function_call 매개 변수는 API의 2023-12-01-preview 버전이 릴리스되어 사용되지 않습니다. functions를 바꾸는 것은 tools 매개 변수입니다. function_call를 바꾸는 것은 tool_choice 매개 변수입니다. 2023-12-01-preview의 일부로 도입된 병렬 함수 호출은 gpt-35-turbo(1106) 및 GPT-4 Turbo Preview로도 알려진 gpt-4(1106-preview)에서만 지원됩니다.

매개 변수 형식 필수 여부 기본값 설명
messages array Required 이 채팅 완료 요청과 관련된 컨텍스트 메시지 모음입니다. 일반적인 사용법은 어시스턴트의 동작에 대한 지침을 제공하는 시스템 역할에 대한 채팅 메시지로 시작하고 사용자와 도우미 역할 간의 메시지가 교대로 이어집니다.
temperature number 선택 사항 1 사용할 샘플링 온도(0에서 2 사이)입니다. 0.8과 같이 값이 높을수록 출력이 더욱 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다. 일반적으로 이를 변경하거나 top_p을(를) 변경하는 것이 좋지만 둘 다 변경하지는 않는 것이 좋습니다.
role string 예 해당 없음 현재 메시지를 제공하는 사용자를 나타냅니다. system,user,assistant,tool, 또는 function일 수 있습니다.
content 문자열 또는 배열 예 해당 없음 메시지의 콘텐츠입니다. 비전 지원 시나리오가 아니라면 문자열이어야 합니다. 최신 API 버전과 함께 비전 모델이 포함된 GPT-4 Turbo를 사용하는 user 메시지의 일부라면 content는 각 항목이 텍스트 또는 이미지를 나타내는 구조의 배열이어야 합니다.
  • text: 입력 텍스트는 속성이 다음과 같은 구조체로 표시됩니다.
    • type = "text"
    • text = 입력 텍스트
  • images: 입력 이미지는 속성이 다음과 같은 구조체로 표시됩니다.
    • type = "image_url"
    • image_url = 속성이 다음과 같은 구조체
      • url = 이미지 URL
      • (선택 사항) detail = high, low 또는 auto
contentPart 개체 아니요 해당 없음 사용자의 다중 모달 메시지 중 일부입니다. 텍스트 형식 또는 이미지 형식일 수 있습니다. 텍스트인 경우 텍스트 문자열이 됩니다. 이미지인 경우 contentPartImage 개체가 됩니다.
contentPartImage 개체 아니요 해당 없음 사용자가 업로드한 이미지를 나타냅니다. 여기에는 url 속성이 있고, 이는 이미지의 URL 또는 Base 64로 인코딩된 이미지 데이터의 URL에 해당합니다. 또한 auto, low 또는 high일 수 있는 detail 속성이 있습니다.
enhancements 개체 아니요 해당 없음 채팅에 요청된 비전 향상 기능을 나타냅니다. grounding 및 ocr 속성이 있으며 각각 부울 enabled 속성이 있습니다. 이를 사용하여 OCR 서비스 및/또는 개체 감지/근거 있는 서비스를 요청합니다. [이 미리 보기 매개 변수는 2024-02-01 GA API에서 사용할 수 없으며 2024-03-01-preview 이후에는 미리 보기 API에서 더 이상 사용할 수 없습니다.]
dataSources 개체 아니요 해당 없음 추가 리소스 데이터를 나타냅니다. 비전 기능을 향상시키려면 Computer Vision 리소스 데이터가 필요합니다. 여기에는 "AzureComputerVision"이어야 하는 type 속성과 endpoint 및 key 속성이 있는 parameters 속성이 있습니다. 이러한 문자열은 Computer Vision 리소스의 엔드포인트 URL 및 액세스 키로 설정해야 합니다.
n 정수 선택 사항 1 각 입력 메시지에 대해 생성할 채팅 완료 선택 항목 수입니다.
stream 부울 값 선택 사항 false 설정되면 ChatGPT의 경우처럼 부분 메시지 델타가 전송됩니다. 토큰은 데이터 전용 서버 전송 이벤트로 전송되며 스트림은 data: [DONE] 메시지로 종료됩니다."
stop 문자열 또는 배열 선택 사항 null API가 추가 토큰 생성을 중지하는 최대 4개의 시퀀스입니다.
max_tokens 정수 선택 사항 inf 생성된 답변에 허용되는 최대 토큰 수입니다. 기본적으로 모델이 반환할 수 있는 토큰 수는 (4096 - 프롬프트 토큰)입니다.
presence_penalty number 선택 사항 0 -2.0~2.0 사이의 숫자 양수 값은 지금까지 텍스트에 나타나는지 여부에 따라 새 토큰에 페널티를 부여하여 모델이 새 항목에 대해 이야기할 가능성을 높입니다.
frequency_penalty number 선택 사항 0 -2.0~2.0 사이의 숫자 양수 값은 지금까지 텍스트의 기존 빈도를 기반으로 새 토큰에 불이익을 주어 모델이 동일한 줄을 그대로 반복할 가능성을 줄입니다.
logit_bias 개체 선택 사항 null 완료 시 지정된 토큰이 나타날 가능성을 수정합니다. 토큰(토크나이저에서 토큰 ID로 지정)을 -100에서 100 사이의 관련 바이어스 값에 매핑하는 json 개체를 허용합니다. 수학적으로, 바이어스는 샘플링 전에 모델에 의해 생성된 로짓에 추가됩니다. 정확한 효과는 모델마다 다르지만, -1과 1 사이의 값은 선택 가능성을 낮추거나 높여야 합니다. -100이나 100 같은 값은 관련 토큰을 금지하거나 독점적으로 선택해야 합니다.
user string 선택 사항 Azure OpenAI가 남용을 모니터링하고 감지하는 데 도움이 될 수 있는 최종 사용자를 나타내는 고유 식별자입니다.
function_call 선택 사항 [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]모델이 함수 호출에 응답하는 방식을 제어합니다. "없음"은 모델이 함수를 호출하지 않고 최종 사용자에게 응답함을 의미합니다. auto는 모델이 최종 사용자와 함수 호출 중에서 선택할 수 있음을 의미합니다. {"name": "my_function"}을 통해 특정 함수를 지정하면 모델이 해당 함수를 호출하게 됩니다. 기능이 없을 경우 "none"이 기본값입니다. 함수가 있는 경우 auto가 기본값입니다. 이 매개 변수에는 API 버전 2023-07-01-preview이 필요합니다.
functions FunctionDefinition[] 선택 사항 [Deprecated in 2023-12-01-preview replacement paremeter is tools] 모델이 JSON 입력을 생성할 수 있는 함수 목록입니다. 이 매개 변수에는 API 버전 2023-07-01-preview이 필요합니다.
tools string(도구의 형식입니다. function만 지원됩니다.) 선택 사항 모델이 호출할 수 있는 도구 목록입니다. 현재 함수만 도구로 지원됩니다. 이를 사용하여 모델이 JSON 입력을 생성할 수 있는 함수 목록을 제공합니다. 이 매개 변수에는 API 버전 2023-12-01-preview이 필요합니다.
tool_choice 문자열 또는 개체 선택 사항 함수가 없는 경우 none이 기본값입니다. 함수가 있는 경우 auto가 기본값입니다. 모델에서 호출되는 함수(해당하는 경우)를 제어합니다. None은 모델이 함수를 호출하지 않고 대신 메시지를 생성함을 의미합니다. auto는 모델이 메시지 생성 또는 함수 호출 중에서 선택할 수 있음을 의미합니다. {"type: "function", "function": {"name": "my_function"}}을 통해 특정 함수를 지정하면 모델이 해당 함수를 호출하게 됩니다. 이 매개 변수에는 API 버전 2023-12-01-preview 이상이 필요합니다.
top_p 번호 아니요 기본값:1
최소:0
최대:1		 모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 밀도를 구성하는 토큰만 고려된다는 의미입니다.\n일반적으로 이 값 또는 temperature를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장되지 않습니다."
log_probs 부울 값 아니요 출력 토큰의 로그 확률을 반환할지 여부를 나타냅니다. true인 경우 message의 content에 반환된 각 출력 토큰의 로그 확률을 반환합니다. 이 옵션은 현재 gpt-4-vision-preview 모델에서는 사용할 수 없습니다.
top_logprobs 정수 아니요 최소: 0
최대: 5		 각 토큰 위치에서 반환될 가능성이 가장 높은 토큰 수를 지정하는 0에서 5 사이의 정수로, 각 토큰에는 관련 로그 가능성이 있습니다. 이 매개 변수를 사용하는 경우 logprobs를 true로 설정해야 합니다.
response_format 개체 아니요 모델이 출력해야 하는 형식을 지정하는 개체입니다. JSON 모드를 사용하도록 설정하는 데 사용됩니다.
seed 정수 아니요 0 지정된 경우 시스템은 동일한 seed 및 매개 변수를 사용하는 반복 요청이 동일한 결과를 반환하도록 결정적으로 샘플링하기 위해 최선을 다합니다. 결정성은 보장되지 않으며 백 엔드의 변경 내용을 모니터링하려면 system_fingerprint 응답 매개 변수를 참조해야 합니다.

모든 API 릴리스에서 모든 매개 변수를 사용할 수 있는 것은 아닙니다.

예제 요청

텍스트 전용 채팅

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure AI services support this too?"}]}'

비전을 사용하는 채팅

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{ "type": "image_url", "image_url": { "url": "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png", "detail": "high" } }]}]}'

비전으로 향상된 채팅

  • GPT-4 Turbo GA 모델에서는 지원되지 않습니다.gpt-4버전:turbo-2024-04-09
  • 2024-02-01및2024-04-01-preview 이상 API 릴리스에서는 지원되지 않습니다.
curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"enhancements":{"ocr":{"enabled":true},"grounding":{"enabled":true}},"dataSources":[{"type":"AzureComputerVision","parameters":{"endpoint":" <Computer Vision Resource Endpoint> ","key":"<Computer Vision Resource Key>"}}],"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{"type":"image_url","image_url":"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"}]}]}'

예제 응답

{
    "id": "chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
    "object": "chat.completion",
    "created": 1679072642,
    "model": "gpt-35-turbo",
    "usage":
    {
        "prompt_tokens": 58,
        "completion_tokens": 68,
        "total_tokens": 126
    },
    "choices":
    [
        {
            "message":
            {
                "role": "assistant",
                "content": "Yes, other Azure AI services also support customer managed keys.
                    Azure AI services offer multiple options for customers to manage keys, such as
                    using Azure Key Vault, customer-managed keys in Azure Key Vault or
                    customer-managed keys through Azure Storage service. This helps customers ensure
                    that their data is secure and access to their services is controlled."
            },
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

읽기 용이성을 위해 조정된 출력 서식입니다. 실제 출력은 줄 바꿈이 없는 단일 텍스트 블록입니다.

예제 응답에서 finish_reason은 stop과 같습니다. finish_reason이 content_filter와 같으면 콘텐츠 필터링 가이드를 참조하여 이 문제가 발생하는 이유를 이해하세요.

채팅메시지

채팅 완료 상호 작용 내의 단일 역할 속성 메시지입니다.

이름 형식 설명
콘텐츠 string 이 메시지 페이로드와 연결된 텍스트입니다.
function_call FunctionCall 모델에 의해 생성된 대로 호출되어야 하는 함수의 이름과 인수입니다.
name string 이 메시지 작성자의 name입니다. 역할이 function인 경우 name이 필요하며 응답이 content에 있는 함수의 이름이어야 합니다. a~z, A~Z, 0~9, 밑줄을 포함할 수 있으며 최대 길이는 64자입니다.
역할(role) 채팅 역할 이 메시지 페이로드와 관련된 역할

채팅역할

채팅 완료 상호작용 내 메시지의 의도된 목적에 대한 설명입니다.

이름 형식 설명
도우미 string 시스템 지시, 사용자 프롬프트 입력에 대한 응답을 제공하는 역할입니다.
function string 채팅 완료에 대한 기능 결과를 제공하는 역할입니다.
시스템 string 도우미의 행동을 지시하거나 설정하는 역할.
user string 채팅 완료를 위한 입력을 제공하는 역할입니다.

함수

2023-12-01-preview API 버전에 추가된 tools 매개 변수와 함께 사용됩니다.

이름 형식 설명
description string 함수를 호출하는 시기과 방법을 선택하기 위해 모델에서 사용하는 함수의 기능에 대한 설명입니다.
name string 호출할 함수의 이름입니다. a~z, A~Z, 0~9 또는 밑줄과 대시를 포함해야 하며 최대 길이는 64자여야 합니다.
매개 변수 개체 함수가 허용하는 매개 변수로, JSON 스키마 개체로 설명됩니다. 형식에 대한 설명서는 JSON 스키마 참조를 참조하세요."

FunctionCall-Deprecated

모델에 의해 생성된 대로 호출되어야 하는 함수의 이름과 인수입니다. 이를 위해서는 API 버전 2023-07-01-preview이 필요합니다.

이름 형식 설명
arguments string JSON 형식의 모델에 의해 생성된 함수 호출에 사용할 인수입니다. 모델이 항상 유효한 JSON을 생성하지는 않고 함수 스키마에서 정의되지 않은 매개 변수를 조작할 수 있습니다. 함수를 호출하기 전에 코드에서 인수의 유효성을 검사하세요.
name string 호출할 함수의 이름입니다.

FunctionDefinition-Deprecated

일치하는 사용자 입력에 대한 응답으로 채팅 완료가 호출될 수 있는 호출자 지정 함수의 정의입니다. 이를 위해서는 API 버전 2023-07-01-preview이 필요합니다.

이름 형식 설명
description string 함수가 수행하는 작업에 대한 설명입니다. 모델이 기능을 선택하고 해당 매개 변수를 해석할 때 이 설명을 사용합니다.
name string 호출할 함수의 이름입니다.
매개 변수 함수가 허용하는 매개 변수로, JSON 스키마 개체로 설명됩니다.

완료 확장

이 섹션에 대한 설명서가 이동되었습니다. 대신 Azure OpenAI On Your Data 참조 설명서를 참조하세요.

이미지 생성

생성된 이미지 요청(DALL-E 3)

텍스트 캡션에서 이미지 배치를 생성 및 검색합니다.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required DALL-E 3 모델 배포의 이름(예: MyDalle3)입니다. 호출하기 전에 먼저 DALL-E 3 모델을 배포해야 합니다.
api-version string Required 이 작업에 사용할 API 버전입니다. YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
prompt string Required 원하는 이미지에 대한 텍스트 설명입니다. 최대 길이는 4,000자입니다.
n 정수 선택 사항 1 생성할 이미지 수입니다. n=1은 DALL-E 3에 한해 지원됩니다.
size string 선택 사항 1024x1024 생성된 이미지의 크기입니다. 1792x1024, 1024x1024 또는 1024x1792 중 하나여야 합니다.
quality string 선택 사항 standard 생성된 이미지의 품질입니다. hd 또는 standard이어야 합니다.
response_format string 선택 사항 url 생성된 이미지가 반환되는 형식은 url(이미지를 가리키는 URL) 또는 b64_json(JSON 형식의 base 64바이트 코드)이어야 합니다.
style string 선택 사항 vivid 생성된 이미지의 스타일입니다. natural 또는 vivid(초현실적/극적 이미지)여야 합니다.
user string 선택 사항 남용을 모니터링하고 감지하는 데 도움이 될 수 있는 최종 사용자를 나타내는 고유 식별자입니다.

Dalle-2는 이제 2024-05-01-preview에서 지원됩니다.

예제 요청

curl -X POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "An avocado chair",
    "size": "1024x1024",
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
  }'

예제 응답

작업은 작업의 ID와 상태를 포함하는 202 상태 코드와 GenerateImagesResponse JSON 개체를 반환합니다.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "url to the image", 
            "revised_prompt": "the actual prompt that was used" 
        }, 
        { 
            "url": "url to the image" 
        },
        ...
    ]
}

생성된 이미지 요청(DALL-E 2 미리 보기)

텍스트 캡션에서 이미지 배치를 생성합니다.

POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
api-version string Required 이 작업에 사용할 API 버전입니다. YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
prompt string Required 원하는 이미지에 대한 텍스트 설명입니다. 최대 길이는 1000자입니다.
n 정수 선택 사항 1 생성할 이미지 수입니다. 1~5 사이여야 합니다.
size string 선택 사항 1024 x 1024 생성된 이미지의 크기입니다. 256x256, 512x512 또는 1024x1024 중 하나여야 합니다.

예제 요청

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/images/generations:submit?api-version=2023-06-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
"prompt": "An avocado chair",
"size": "512x512",
"n": 3
}'

예제 응답

작업은 작업의 ID와 상태를 포함하는 202 상태 코드와 GenerateImagesResponse JSON 개체를 반환합니다.

{
  "id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
  "status": "notRunning"
}

생성된 이미지 결과 가져오기(DALL-E 2 미리 보기)

이 API를 사용하여 이미지 생성 작업의 결과를 검색합니다. 이미지 생성은 현재 api-version=2023-06-01-preview에서만 가능합니다.

GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
operation-id string Required 원본 이미지 생성 요청을 식별하는 GUID입니다.

지원되는 버전

예제 요청

curl -X GET "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

예제 응답

성공하면 작업이 200 상태 코드와 OperationResponse JSON 개체를 반환합니다. status 필드는 "notRunning"(작업이 큐에 있지만 아직 시작되지 않음), "running", "succeeded", "canceled"(작업 시간이 초과됨), "failed" 또는 "deleted"일 수 있습니다. succeeded 상태는 생성된 이미지를 해당 URL에서 다운로드할 수 있음을 나타냅니다. 여러 이미지가 생성된 경우 해당 URL은 모두 result.data 필드에 반환됩니다.

{
  "created": 1685064331,
  "expires": 1685150737,
  "id": "4b755937-3173-4b49-bf3f-da6702a3971a",
  "result": {
    "data": [
      {
        "url": "<URL_TO_IMAGE>"
      },
      {
        "url": "<URL_TO_NEXT_IMAGE>"
      },
      ...
    ]
  },
  "status": "succeeded"
}

서버에서 생성된 이미지 삭제(DALL-E 2 미리 보기)

요청에서 반환된 작업 ID를 사용하여 Azure 서버에서 해당 이미지를 삭제할 수 있습니다. 생성된 이미지는 기본적으로 24시간 후에 자동으로 삭제되지만 원하는 경우 더 일찍 삭제를 실행할 수 있습니다.

DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
operation-id string Required 원본 이미지 생성 요청을 식별하는 GUID입니다.

지원되는 버전

예제 요청

curl -X DELETE "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

응답

작업이 성공하면 204 상태 코드를 반환합니다. 이 API는 작업이 종료 상태(running 아님)에 있는 경우에만 성공합니다.

음성 텍스트 변환

음성 텍스트 변환 또는 음성 번역을 위해 Azure OpenAI Service에서 Whisper 모델을 사용할 수 있습니다. Whisper 모델 사용에 대한 자세한 내용은 빠른 시작과 Whisper 모델 개요를 참조하세요.

음성 텍스트 변환 전사 요청

오디오 파일을 기록합니다.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required MyWhisperDeployment와 같은 Whisper 모델 배포의 이름입니다. 전화를 걸려면 먼저 Whisper 모델을 배포해야 합니다.
api-version string Required 이 작업에 사용할 API 버전입니다. 이 값은 YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
file 파일 예 해당 없음 flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm 형식 중 하나로 기록할 오디오 파일 개체(파일 이름 아님)입니다.

Azure OpenAI Service의 Whisper 모델에 대한 파일 크기 제한은 25MB입니다. 25MB보다 큰 파일을 전사해야 하는 경우 청크로 분할합니다. 또는 Azure AI Speech 일괄 처리 전사 API를 사용할 수 있습니다.

GitHub의 Azure AI Speech SDK 리포지토리에서 샘플 오디오 파일을 가져올 수 있습니다.
language string 아니요 Null fr와 같은 입력 오디오의 언어입니다. ISO-639-1 형식으로 입력 언어를 제공하면 정확도와 대기 시간이 향상됩니다.

지원되는 언어 목록은 OpenAI 설명서를 참조하세요.
prompt string 아니요 Null 모델 스타일을 안내하거나 이전 오디오 세그먼트를 계속 진행하기 위한 선택적 텍스트입니다. 프롬프트는 오디오 언어와 일치해야 합니다.

사용 사례 예제를 비롯한 프롬프트에 대한 자세한 내용은 OpenAI 설명서를 참조하세요.
response_format string 아니요 json json, text, srt, verbose_json 또는 vtt 옵션 중 하나에 있는 전사 출력의 형식입니다.

기본값은 json입니다.
temperature number 아니요 0 샘플링 온도(0에서 1 사이)입니다.

0.8과 같이 값이 높을수록 출력이 더 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다. 0으로 설정하면 모델은 로그 확률을 사용하여 특정 임계값에 도달할 때까지 온도를 자동으로 높입니다.

기본값은 0입니다.
timestamp_granularities array 선택 사항 세그먼트 이 대화 내용 기록을 위해 채울 타임스탬프 세분성입니다. 타임스탬프 세분성을 사용하려면 response_format을 verbose_json으로 설정해야 합니다. word 또는 segment 옵션 중 하나 또는 둘 다 지원됩니다. 참고: 세그먼트 타임스탬프에 대한 추가 대기 시간은 없지만 단어 타임스탬프를 생성하면 추가 대기 시간이 발생합니다. [2024-04-01-prevew에 추가됨]

예제 요청

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/transcriptions?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "language=en" \
  -F "prompt=The transcript contains zoology terms and geographical locations." \
  -F "temperature=0" \
  -F "response_format=srt"

예제 응답

1
00:00:00,960 --> 00:00:07,680
The ocelot, Lepardus paradalis, is a small wild cat native to the southwestern United States,

2
00:00:07,680 --> 00:00:13,520
Mexico, and Central and South America. This medium-sized cat is characterized by

3
00:00:13,520 --> 00:00:18,960
solid black spots and streaks on its coat, round ears, and white neck and undersides.

4
00:00:19,760 --> 00:00:27,840
It weighs between 8 and 15.5 kilograms, 18 and 34 pounds, and reaches 40 to 50 centimeters

5
00:00:27,840 --> 00:00:34,560
16 to 20 inches at the shoulders. It was first described by Carl Linnaeus in 1758.

6
00:00:35,360 --> 00:00:42,880
Two subspecies are recognized, L. p. paradalis and L. p. mitis. Typically active during twilight

7
00:00:42,880 --> 00:00:48,480
and at night, the ocelot tends to be solitary and territorial. It is efficient at climbing,

8
00:00:48,480 --> 00:00:54,480
leaping, and swimming. It preys on small terrestrial mammals such as armadillo, opossum,

9
00:00:54,480 --> 00:00:56,480
and lagomorphs.

음성 텍스트 변환 요청

다른 언어의 오디오 파일을 영어로 변환합니다. 지원되는 언어 목록은 OpenAI 설명서를 참조하세요.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required MyWhisperDeployment와 같은 Whisper 모델 배포의 이름입니다. 전화를 걸려면 먼저 Whisper 모델을 배포해야 합니다.
api-version string Required 이 작업에 사용할 API 버전입니다. 이 값은 YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
file 파일 예 해당 없음 flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav 또는 webm 형식 중 하나로 기록할 오디오 파일 개체(파일 이름 아님)입니다.

Azure OpenAI Whisper 모델의 파일 크기 제한은 25MB입니다. 25MB보다 큰 파일을 전사해야 하는 경우 청크로 분할합니다.

GitHub의 Azure AI Speech SDK 리포지토리에서 샘플 오디오 파일을 다운로드할 수 있습니다.
prompt string 아니요 Null 모델 스타일을 안내하거나 이전 오디오 세그먼트를 계속 진행하기 위한 선택적 텍스트입니다. 프롬프트는 오디오 언어와 일치해야 합니다.

사용 사례 예제를 비롯한 프롬프트에 대한 자세한 내용은 OpenAI 설명서를 참조하세요.
response_format string 아니요 json json, text, srt, verbose_json 또는 vtt 옵션 중 하나에 있는 전사 출력의 형식입니다.

기본값은 json입니다.
temperature number 아니요 0 샘플링 온도(0에서 1 사이)입니다.

0.8과 같이 값이 높을수록 출력이 더 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다. 0으로 설정하면 모델은 로그 확률을 사용하여 특정 임계값에 도달할 때까지 온도를 자동으로 높입니다.

기본값은 0입니다.

예제 요청

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/translations?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "temperature=0" \
  -F "response_format=json"

예제 응답

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

텍스트 음성 변환

텍스트 음성 변환 합성

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

경로 매개 변수

매개 변수 형식 필수 여부 설명
your-resource-name string Required Azure OpenAI 리소스의 이름입니다.
deployment-id string Required 텍스트 음성 변환 모델 배포의 이름(예: MyTextToSpeechDeployment)입니다. 호출하려면 먼저 텍스트 음성 변환 모델(예: tts-1 또는 tts-1-hd)을 배포해야 합니다.
api-version string Required 이 작업에 사용할 API 버전입니다. 이 값은 YYYY-MM-DD 형식을 따릅니다.

지원되는 버전

요청 본문

매개 변수 형식 필수 여부 기본값 설명
model string 예 해당 없음 사용 가능한 TTS 모델(tts-1 또는 tts-1-hd) 중 하나입니다.
input string 예 해당 없음 오디오를 생성할 텍스트입니다. 최대 길이는 4,096자입니다. 선택한 언어로 입력 텍스트를 지정합니다.1
voice string 예 해당 없음 오디오를 생성할 때 사용할 음성입니다. 지원되는 음성은 alloy, echo, fable, onyxnova, shimmer입니다. 음성 미리 보기는 OpenAI 텍스트 음성 변환 가이드에서 확인할 수 있습니다.

1 텍스트 음성 변환 모델은 일반적으로 위스퍼 모델과 동일한 언어를 지원합니다. 지원되는 언어 목록은 OpenAI 설명서를 참조하세요.

예제 요청

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

예제 응답

음성은 이전 요청의 오디오 파일로 반환됩니다.

관리 API

Azure OpenAI는 Azure AI 서비스의 일부로 배포됩니다. 모든 Azure AI 서비스는 생성, 업데이트 및 삭제 작업에 동일한 관리 API 세트를 사용합니다. 관리 API는 Azure OpenAI 리소스 내에 모델을 배포하는 데에도 사용됩니다.

관리 API 참조 설명서

다음 단계

모델 및 REST API를 사용한 미세 조정에 대해 알아보세요. Azure OpenAI를 지원하는 기본 모델에 대해 자세히 알아봅니다.