본문으로 건너뛰기

텍스트 생성하기

작업에 맞는 API 형식 선택

텍스트 생성, 이미지 입력, 도구 호출과 임베딩에 사용하는 API 형식을 비교하고 기능별 명세 위치를 안내하며, 모든 모델에 같은 것과 모델마다 확인할 것을 구분합니다.

페이지 목차

지원 범위

AI 게이트웨이의 텍스트 API 형식으로 다음 일을 할 수 있습니다. 어떤 형식으로 요청할지는 API 형식 선택에서 고릅니다.

하려는 일보내는 입력과 받는 결과
텍스트 생성과 대화메시지 배열이나 입력 문자열을 보내고 모델의 응답 텍스트를 받음. 이전 대화를 함께 보내 대화를 이어 감
이미지 입력텍스트와 함께 이미지 URL이나 Base64 이미지를 보내고, 두 입력을 바탕으로 한 응답 텍스트를 받음
도구 호출애플리케이션이 실행할 함수의 이름과 입력 형식을 보내고, 모델이 요청한 함수 이름과 인수를 받음. 함수는 애플리케이션이 실행하고 그 결과를 다음 요청에 포함해 보냄
임베딩단일 문자열이나 입력 배열을 보내고, 검색과 유사도 계산에 쓰는 텍스트 벡터를 받음

API 형식이 기능을 제공하더라도 요청한 모델이 그 형식과 기능을 지원해야 합니다. 현재 스페이스에서 사용할 수 있는 모델과 모델 코드, 지원 API, 단가는 에셋에서 확인합니다.

이미지를 생성하려면 이미지와 영상 만들기에서 이미지 생성 모델과 호출 경로를 확인해 선택합니다. 에셋 화면의 기본 모델 탭에 있는 이미지 모델의 호출 방법과, Chat Completions 응답으로 생성 이미지를 받는 모델의 호출 방법도 그 페이지에 있습니다.

API 형식 선택

모델 이름만 보고 API 형식을 정하지 않습니다. 에셋 화면에서 사용할 모델의 지원 API를 확인한 뒤, 아래 표에서 하려는 일에 맞는 형식을 선택합니다.

API 형식선택하는 경우와 SDK, 기본 URL
Chat Completions POST /v1/chat/completionsmessages 배열로 대화를 보내고 OpenAI 호환 응답을 받을 때. 기존 OpenAI 호환 코드는 base URL, API 키와 모델 코드를 바꿔 사용. OpenAI 호환 SDK 또는 HTTP로 https://gw.letsur.ai/v1에 요청
Responses POST /v1/responsesinput과 instructions로 요청하고, 응답 상태 status와 output[] 블록으로 결과를 받을 때. 사용할 모델의 Responses 지원 여부를 먼저 확인. OpenAI 호환 SDK 또는 HTTP로 https://gw.letsur.ai/v1에 요청
Messages POST /v1/messagesAnthropic Messages 형식으로 요청할 때. Anthropic SDK나 Claude Code에서 사용. Messages를 지원하는 모델은 Messages 지원 범위에서 확인. https://gw.letsur.ai에 요청
Embeddings POST /v1/embeddings검색과 유사도 계산을 위해 텍스트를 벡터로 바꿀 때. OpenAI 호환 SDK 또는 HTTP로 https://gw.letsur.ai/v1에 요청

API 형식마다 요청과 응답 형식이 다릅니다. 예를 들어 Messages 요청으로 도구 실행 결과를 전달할 때 Chat Completions의 role: "tool" 형식을 섞지 않습니다.

SDK의 기본 URL은 API 형식마다 다릅니다. 형식별 인증 헤더와 기본 URL은 인증과 기본 URL에서 확인합니다.

기능별 명세 위치

같은 기능이라도 API 형식마다 요청하는 방법과 응답에서 읽는 위치가 다릅니다. 아래 표에서 사용할 형식의 명세 절을 찾습니다. 명세에 설명이 없는 항목은 표에 설명 없음으로 표시했습니다.

기능Chat CompletionsResponsesMessages
스트리밍스트리밍스트리밍 이벤트스트리밍
이미지 입력이미지 입력설명 없음설명 없음
도구 호출도구 호출함수 도구 정의와 결과 반환함수 도구 정의하기와 도구 실행 결과 반환
출력 형식 지정response_format (요청 필드)text.format (요청 필드)설명 없음
응답 종료 이유finish_reason (종료 이유에 따른 다음 행동)status (응답 상태에 따른 다음 행동)stop_reason (종료 이유에 따른 다음 행동)

Responses 응답의 출력 항목 종류와 도구 실행 결과를 전달할 때 보존할 항목은 Responses 명세에서 확인합니다.

Embeddings는 위 표에 없습니다. Embeddings의 스트리밍 지원 여부와 호출 방식은 Embeddings 지원 범위에서 확인합니다.

공통 사항과 모델별 차이

AI 게이트웨이에서는 여러 공급사의 모델을 각 모델이 지원하는 API 형식으로 호출합니다. 그래서 문서의 설명 가운데 어떤 것은 모든 모델에 적용되고, 어떤 것은 모델마다 다릅니다. 요청을 작성하기 전에 각 설명의 적용 범위를 확인하세요.

적용 범위내용과 확인할 곳
모든 모델인증. API 형식이 같으면 모델과 관계없이 같은 인증 헤더와 기본 URL 사용. 인증과 기본 URL
모든 모델Chat Completions, Responses, Messages, Embeddings의 비스트리밍 응답 최상위에 있는 호출별 비용 estimated_cost. 요청별 비용
텍스트와 임베딩 API오류 응답의 구조와 재시도 기준. 오류 코드
모델마다 다름이미지 입력, 도구 호출, JSON 모드, 스트리밍의 지원 여부와 세부 제한. 이미지 크기와 해상도 제한, 입력 토큰 한도. 에셋 화면의 표시값

텍스트 모델에는 모델별 가이드가 없습니다. 모델마다 다른 기능은 다음 기준으로 확인합니다.

  • 지원 여부: 에셋 화면에서 확인합니다. 프로그램에서 모델 목록을 조회할 때는 Models API를 씁니다. Models API는 모델 코드와 함께 pricing과 supports_batch 필드를 반환합니다. 에셋에 정보가 없다는 이유로 한도가 없거나 필요한 기능을 지원한다고 판단하지 마세요. 에셋에 표시된 정보만으로 지원 여부를 확인할 수 없다면 모델 비교 항목에 안내된 문의 방법을 따르세요.
  • 지원하지 않는 파라미터: 모델이 지원하지 않는 파라미터를 넣은 요청은 실패할 수 있습니다. 반환되는 오류 코드는 각 명세의 오류 절에 있습니다. 예를 들어 Chat Completions에서 이미지 입력이나 응답 형식을 지원하지 않는 모델에 보낸 요청의 오류 코드는 Chat Completions의 오류와 복구에서 볼 수 있습니다.
  • 출력 상한 필드 이름: 모델에 따라 다릅니다. 모델별 필드 이름은 Batch 입력 기준으로 Batch Files의 모델별 입력 조건에 정리되어 있습니다. 특정 모델이 파라미터를 지원하는지는 에셋 화면에서 확인합니다.

다음 단계

API 형식을 정했다면 사용할 모델의 코드로 첫 요청을 보냅니다. 많은 요청을 파일로 묶어 처리하려면 Batch 입력 조건을 별도로 확인합니다.