OpenAI 멀티모달 Responses API

curl https://api.apimart.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "model": "gpt-5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "이 이미지에는 무엇이 있습니까?"
          },
          {
            "type": "input_image",
            "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
          }
        ]
      }
    ]
  }'

{
  "code": 200,
  "data": {
    "id": "resp-9876543210",
    "object": "response",
    "created": 1677652288,
    "model": "gpt-5",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "이 이미지에는 고양이와 수달이 있습니다. 매우 귀엽고 훈훈한 장면으로 서로 교감하고 있는 것처럼 보입니다. 고양이와 수달이 사이좋게 지내고 있는 것 같습니다."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 156,
      "completion_tokens": 45,
      "total_tokens": 201
    }
  }
}

POST

responses

curl https://api.apimart.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "model": "gpt-5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "이 이미지에는 무엇이 있습니까?"
          },
          {
            "type": "input_image",
            "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
          }
        ]
      }
    ]
  }'

{
  "code": 200,
  "data": {
    "id": "resp-9876543210",
    "object": "response",
    "created": 1677652288,
    "model": "gpt-5",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "이 이미지에는 고양이와 수달이 있습니다. 매우 귀엽고 훈훈한 장면으로 서로 교감하고 있는 것처럼 보입니다. 고양이와 수달이 사이좋게 지내고 있는 것 같습니다."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 156,
      "completion_tokens": 45,
      "total_tokens": 201
    }
  }
}

curl https://api.apimart.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "model": "gpt-5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "이 이미지에는 무엇이 있습니까?"
          },
          {
            "type": "input_image",
            "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"
          }
        ]
      }
    ]
  }'

{
  "code": 200,
  "data": {
    "id": "resp-9876543210",
    "object": "response",
    "created": 1677652288,
    "model": "gpt-5",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "이 이미지에는 고양이와 수달이 있습니다. 매우 귀엽고 훈훈한 장면으로 서로 교감하고 있는 것처럼 보입니다. 고양이와 수달이 사이좋게 지내고 있는 것 같습니다."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 156,
      "completion_tokens": 45,
      "total_tokens": 201
    }
  }
}

Authorizations

Authorization

string

필수

##모든 API는 Bearer Token 인증이 필요합니다##API 키 가져오기:API 키 관리 페이지를 방문하여 API 키를 받으세요요청 헤더에 추가:

Authorization: Bearer YOUR_API_KEY

Body

model

string

기본값:"gpt-5"

필수

모델 이름지원되는 모델:

gpt-5 - OpenAI 최신 멀티모달 모델
GPT-4o-image - GPT-4 최적화 멀티모달 모델
gpt-4-vision - GPT-4 비전 이해 모델
더 많은 모델이 곧 출시될 예정입니다…

input

array

필수

입력 콘텐츠 목록입력 배열, 각 항목은 role과 content 필드를 포함합니다.💡 빠른 입력 (Try it 영역):

”+ Add an item”을 클릭하여 입력 항목 추가
role 입력: user (사용자 메시지), assistant (AI 응답), 또는 system (시스템 프롬프트)
content 콘텐츠 블록 추가 (텍스트와 이미지 포함 가능)

표시 필드 상세

role

string

기본값:"user"

필수

역할 유형선택 가능: user (사용자 메시지), assistant (AI 응답, 다중 턴용), system (시스템 프롬프트, AI 동작 설정)

content

array

필수

콘텐츠 배열여러 유형의 콘텐츠 블록을 지원하며, 텍스트와 이미지를 포함할 수 있습니다.

표시 콘텐츠 블록 유형

type

string

필수

콘텐츠 유형선택 가능:

input_text: 텍스트 입력
input_image: 이미지 입력

text

string

텍스트 내용type이 input_text일 때 사용, 텍스트 내용 입력

image_url

string

이미지 URLtype이 input_image일 때 사용, 이미지 URL 또는 base64 인코딩 입력두 가지 형식을 지원합니다:1. 전체 이미지 URL

공개적으로 접근 가능한 이미지 URL (http:// 또는 https://)
예: https://example.com/image.jpg

2. Base64 인코딩 형식

완전한 Data URI 형식을 사용해야 합니다
형식: data:image/{format};base64,{base64_data}
지원 이미지 형식: jpeg, png, gif, webp

temperature

number

출력 무작위성 제어, 범위 0-2

낮은 값 (예: 0.2)은 출력을 더 결정적으로 만듭니다
높은 값 (예: 1.8)은 출력을 더 무작위로 만듭니다

기본값: 1.0

max_tokens

integer

생성할 최대 토큰 수모델마다 최대 제한이 다르므로 특정 모델 문서를 참조하세요

stream

boolean

스트리밍 출력 사용 여부

true: 스트림 응답 (SSE 형식)
false: 전체 응답을 한 번에 반환

기본값: false

top_p

number

Nucleus 샘플링 매개변수, 범위 0-1생성된 텍스트의 다양성을 제어하며, temperature와 번갈아 사용하는 것을 권장합니다기본값: 1.0

tools

array

모델 기능을 확장하기 위한 도구 목록지원되는 도구 유형:

웹 검색 (web_search): 실시간 인터넷 정보 검색
파일 검색 (file_search): 업로드된 파일 콘텐츠 검색
함수 호출 (function): 사용자 정의 함수 호출
원격 MCP (remote_mcp): 원격 Model Context Protocol 서비스에 연결

예시: [{"type": "web_search"}]

Response

string

응답의 고유 식별자

object

string

객체 유형, response로 고정

created

integer

생성 타임스탬프

model

string

사용된 실제 모델 이름

choices

array

생성된 응답 목록

표시 Properties

index

integer

선택 인덱스

message

object

메시지 내용

표시 Properties

role

string

역할 유형 (assistant)

content

string

생성된 텍스트 내용

finish_reason

string

종료 이유가능한 값:

stop - 자연스러운 완료
length - 최대 길이 도달
content_filter - 콘텐츠 필터링

usage

object

토큰 사용 통계

표시 Properties

prompt_tokens

integer

입력의 토큰 수

completion_tokens

integer

출력의 토큰 수

total_tokens

integer

총 토큰 수

사용 예시

텍스트 전용 입력

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "안녕하세요, 인공지능을 소개해주세요"
        }
      ]
    }
  ]
}

웹 검색 도구 사용

{
  "model": "gpt-5",
  "tools": [{"type": "web_search"}],
  "input": "오늘 어떤 긍정적인 뉴스가 있나요?"
}

cURL 예시

curl "https://api.apimart.ai/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{
        "model": "gpt-5",
        "tools": [{"type": "web_search"}],
        "input": "오늘 어떤 긍정적인 뉴스가 있나요?"
    }'

이미지 이해

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "이 이미지를 설명해주세요"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image.jpg"
        }
      ]
    }
  ]
}

다중 이미지 분석

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "이 두 이미지의 유사점과 차이점을 비교해주세요"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image1.jpg"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image2.jpg"
        }
      ]
    }
  ]
}

Base64 인코딩 이미지

{
  "model": "gpt-5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "이 이미지를 분석해주세요"
        },
        {
          "type": "input_image",
          "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
        }
      ]
    }
  ]
}

파일 검색 도구 사용

{
  "model": "gpt-5",
  "tools": [{"type": "file_search"}],
  "input": "업로드된 문서를 기반으로 회사의 분기별 실적을 요약해주세요"
}

함수 호출 사용

{
  "model": "gpt-5",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "지정된 도시의 날씨 정보 가져오기",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "도시 이름, 예: 서울"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "온도 단위"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "input": "오늘 서울의 날씨는 어떤가요?"
}

원격 MCP 사용

{
  "model": "gpt-5",
  "tools": [
    {
      "type": "remote_mcp",
      "remote_mcp": {
        "url": "https://mcp.example.com/api",
        "auth_token": "your_mcp_token"
      }
    }
  ],
  "input": "데이터베이스에서 사용자 정보를 조회해주세요"
}

여러 도구 결합

{
  "model": "gpt-5",
  "tools": [
    {"type": "web_search"},
    {"type": "file_search"},
    {
      "type": "function",
      "function": {
        "name": "calculate",
        "description": "수학 계산 수행",
        "parameters": {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "수학 표현식"
            }
          },
          "required": ["expression"]
        }
      }
    }
  ],
  "input": "최신 비트코인 가격을 검색하고 비트코인 100개의 총 가치를 계산해주세요"
}

콘텐츠 유형 사양

input_text

텍스트 입력 유형 속성:

type: "input_text"로 고정
text: 텍스트 내용 (문자열)

input_image

이미지 입력 유형 속성:

type: "input_image"로 고정
image_url: 이미지 URL 또는 Base64 인코딩된 데이터 URI

지원되는 이미지 형식:

JPEG
PNG
GIF
WebP

이미지 크기 제한:

최대 파일 크기: 20MB
권장 해상도: 2048x2048 픽셀 이하

도구 사용 세부 정보

웹 검색

웹 검색 도구를 사용하면 모델이 실시간 인터넷 정보에 접근할 수 있습니다. 구성 예시:

{
  "tools": [{"type": "web_search"}]
}

사용 사례:

최신 뉴스 및 시사 조회
실시간 데이터 가져오기 (주식, 날씨, 환율 등)
최신 기술 문서 검색
사실 정보 확인

파일 검색

파일 검색 도구를 사용하면 모델이 업로드된 문서에서 관련 정보를 검색할 수 있습니다. 구성 예시:

{
  "tools": [{"type": "file_search"}]
}

사용 사례:

회사 내부 문서 분석
기술 사양 및 매뉴얼 검색
계약서 및 법률 문서 조회
지식 베이스 Q&A 시스템

함수 호출

사용자 정의 함수를 정의하여 모델이 외부 API를 호출하거나 특정 작업을 수행할 수 있게 합니다. 전체 구성 예시:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "실시간 주가 가져오기",
        "parameters": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "주식 기호, 예: AAPL"
            },
            "currency": {
              "type": "string",
              "enum": ["USD", "CNY"],
              "description": "통화 단위",
              "default": "USD"
            }
          },
          "required": ["symbol"]
        }
      }
    }
  ]
}

매개변수 설명:

name: 함수 이름 (필수)
description: 함수 설명 (필수)
parameters: JSON Schema 형식을 사용한 매개변수 정의
- type: 매개변수 유형
- properties: 매개변수 속성 정의
- required: 필수 매개변수 목록

사용 사례:

타사 API 호출
데이터베이스 쿼리 실행
비즈니스 프로세스 트리거
내부 시스템과 통합

원격 MCP

원격 Model Context Protocol (MCP) 서비스에 연결하여 모델 기능을 확장합니다. 구성 예시:

{
  "tools": [
    {
      "type": "remote_mcp",
      "remote_mcp": {
        "url": "https://your-mcp-server.com/api",
        "auth_token": "your_auth_token",
        "timeout": 30
      }
    }
  ]
}

매개변수 설명:

url: MCP 서버 주소 (필수)
auth_token: 인증 토큰 (선택)
timeout: 타임아웃(초), 기본값 30초

사용 사례:

기업급 AI 서비스에 연결
도메인별 모델 사용
보호된 데이터 소스에 접근
분산 AI 시스템 통합

도구 응답 형식

모델이 도구를 사용하면 응답 형식에 도구 호출 정보가 포함됩니다:

{
  "id": "resp-123456",
  "object": "response",
  "created": 1677652288,
  "model": "gpt-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"서울\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

도구 호출 워크플로:

모델이 사용자 입력을 수신
도구가 필요한지 분석
필요한 경우 도구 호출 요청 반환
클라이언트가 도구 호출 실행
도구 결과를 모델에 반환
모델이 최종 응답 생성

중요 참고 사항

이미지 URL 요구 사항:
- 공개적으로 접근 가능한 URL이어야 합니다
- 또는 Base64 인코딩된 Data URI 형식 사용
토큰 청구:
- 이미지는 해상도에 따라 토큰을 소비합니다
- 고해상도 이미지는 비용 최적화를 위해 자동으로 크기가 조정됩니다
- 도구 호출도 추가 토큰을 소비합니다
콘텐츠 순서:
- 콘텐츠 배열의 요소 순서가 모델 이해에 영향을 줍니다
- 텍스트 지시사항을 먼저, 그다음 이미지를 배치하는 것을 권장합니다
멀티모달 조합:
- 하나의 요청에서 여러 텍스트와 이미지를 혼합할 수 있습니다
- 컨텍스트 일관성을 유지하는 다중 턴 대화를 지원합니다
도구 사용 제한 사항:
- 여러 도구를 동시에 사용할 때 모델이 가장 적절한 도구를 지능적으로 선택합니다
- 함수 호출에는 명확한 함수 정의와 매개변수 설명이 필요합니다
- 웹 검색 결과는 지역 및 시간에 따라 제한될 수 있습니다
API 호환성:
- OpenAI Responses API 형식과 완전히 호환됩니다
- 기존 OpenAI 코드를 원활하게 마이그레이션할 수 있습니다
- 모든 OpenAI 도구 확장 기능을 지원합니다

Gemini 네이티브 형식 Gemini-3.1-Flash-Image-preview (Nano banana2) 이미지 생성

Documentation Index

​Authorizations

​Body

​Response

​사용 예시

​텍스트 전용 입력

​웹 검색 도구 사용

​이미지 이해

​다중 이미지 분석

​Base64 인코딩 이미지

​파일 검색 도구 사용

​함수 호출 사용

​원격 MCP 사용

​여러 도구 결합

​콘텐츠 유형 사양

​input_text

​input_image

​도구 사용 세부 정보

​웹 검색

​파일 검색

​함수 호출

​원격 MCP

​도구 응답 형식

​중요 참고 사항

Authorizations

Body

Response

사용 예시

텍스트 전용 입력

웹 검색 도구 사용

이미지 이해

다중 이미지 분석

Base64 인코딩 이미지

파일 검색 도구 사용

함수 호출 사용

원격 MCP 사용

여러 도구 결합

콘텐츠 유형 사양

input_text

input_image

도구 사용 세부 정보

웹 검색

파일 검색

함수 호출

원격 MCP

도구 응답 형식

중요 참고 사항