메인 콘텐츠로 건너뛰기
POST
https://api.apimart.ai
/
v1
/
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
required
##모든 API는 Bearer Token 인증이 필요합니다##API 키 가져오기:API 키 관리 페이지를 방문하여 API 키를 받으세요요청 헤더에 추가:
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
default:"gpt-5"
required
모델 이름지원되는 모델:
  • gpt-5 - OpenAI 최신 멀티모달 모델
  • GPT-4o-image - GPT-4 최적화 멀티모달 모델
  • gpt-4-vision - GPT-4 비전 이해 모델
  • 더 많은 모델이 곧 출시될 예정입니다…
​
input
array
required
입력 콘텐츠 목록입력 배열, 각 항목은 role과 content 필드를 포함합니다.💡 빠른 입력 (Try it 영역):
  1. ”+ Add an item”을 클릭하여 입력 항목 추가
  2. role 입력: user (사용자 메시지), assistant (AI 응답), 또는 system (시스템 프롬프트)
  3. content 콘텐츠 블록 추가 (텍스트와 이미지 포함 가능)
​
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

​
id
string
응답의 고유 식별자
​
object
string
객체 유형, response로 고정
​
created
integer
생성 타임스탬프
​
model
string
사용된 실제 모델 이름
​
choices
array
생성된 응답 목록
​
usage
object
토큰 사용 통계

​
사용 예시

​
텍스트 전용 입력

{
  "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"
    }
  ]
}
도구 호출 워크플로:
  1. 모델이 사용자 입력을 수신
  2. 도구가 필요한지 분석
  3. 필요한 경우 도구 호출 요청 반환
  4. 클라이언트가 도구 호출 실행
  5. 도구 결과를 모델에 반환
  6. 모델이 최종 응답 생성

​
중요 참고 사항

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