curl https://api.apimart.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-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
##모든 API는 Bearer Token 인증이 필요합니다##API 키 가져오기:API 키 관리 페이지를 방문하여 API 키를 받으세요요청 헤더에 추가:Authorization: Bearer YOUR_API_KEY
Body
모델 이름지원되는 모델:
gpt-5 - OpenAI 최신 멀티모달 모델GPT-4o-image - GPT-4 최적화 멀티모달 모델gpt-4-vision - GPT-4 비전 이해 모델- 더 많은 모델이 곧 출시될 예정입니다…
입력 콘텐츠 목록각 입력 항목에는 다음이 포함됩니다:
role: 역할 유형 (user, assistant, system)content: 콘텐츠 배열, 여러 유형 지원:
input_text: 텍스트 입력input_image: 이미지 입력
출력 무작위성 제어, 범위 0-2
- 낮은 값 (예: 0.2)은 출력을 더 결정적으로 만듭니다
- 높은 값 (예: 1.8)은 출력을 더 무작위로 만듭니다
기본값: 1.0 생성할 최대 토큰 수모델마다 최대 제한이 다르므로 특정 모델 문서를 참조하세요
스트리밍 출력 사용 여부
true: 스트림 응답 (SSE 형식)false: 전체 응답을 한 번에 반환
기본값: false Nucleus 샘플링 매개변수, 범위 0-1생성된 텍스트의 다양성을 제어하며, temperature와 번갈아 사용하는 것을 권장합니다기본값: 1.0
모델 기능을 확장하기 위한 도구 목록지원되는 도구 유형:
- 웹 검색 (
web_search): 실시간 인터넷 정보 검색
- 파일 검색 (
file_search): 업로드된 파일 콘텐츠 검색
- 함수 호출 (
function): 사용자 정의 함수 호출
- 원격 MCP (
remote_mcp): 원격 Model Context Protocol 서비스에 연결
예시: [{"type": "web_search"}] Response
생성된 응답 목록
종료 이유가능한 값:
stop - 자연스러운 완료length - 최대 길이 도달content_filter - 콘텐츠 필터링
사용 예시
텍스트 전용 입력
{
"model": "gpt-5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "안녕하세요, 인공지능을 소개해주세요"
}
]
}
]
}
웹 검색 도구 사용
{
"model": "gpt-5",
"tools": [{"type": "web_search"}],
"input": "오늘 어떤 긍정적인 뉴스가 있나요?"
}
curl "https://api.apimart.ai/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-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: 텍스트 내용 (문자열)
이미지 입력 유형
속성:
type: "input_image"로 고정image_url: 이미지 URL 또는 Base64 인코딩된 데이터 URI
지원되는 이미지 형식:
이미지 크기 제한:
- 최대 파일 크기: 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 도구 확장 기능을 지원합니다