GPT Actions로 파일 보내고 반환하기

GPT Actions에서 대화에 포함된 파일을 API로 보내고, 반대로 API가 파일을 반환하는 방법을 다루는 가이드예요. openaiFileIdRefs와 openaiFileResponse 파라미터 사용법을 배워요.

출처: 문서

본문

파일 보내기 (Sending files)

POST 요청에는 대화에서 가져온 최대 10개의 파일(DALL-E 생성 이미지 포함)을 포함할 수 있어요. 이 파일들은 5분 동안 유효한 URL로 전송돼요.

파일이 POST 요청의 일부가 되려면 파라미터 이름을 openaiFileIdRefs로 지정해야 하며, description(설명)은 여러분의 API가 기대하는 파일의 유형과 수량을 모델에 설명해야 해요.

openaiFileIdRefs 파라미터는 JSON 객체 배열로 채워져요. 각 객체는 다음을 포함해요:

name 파일 이름. DALL-E로 생성된 경우 자동 생성된 이름이에요.
id 파일의 안정적인 식별자.
mime_type 파일의 MIME 타입. 사용자가 업로드한 파일의 경우 파일 확장자에 기반해요.
download_link 파일을 가져오기 위한 URL. 5분 동안 유효해요.

다음은 두 요소를 가진 openaiFileIdRefs 배열의 예시예요:

[
  {
    "name": "dalle-Lh2tg7WuosbyR9hk",
    "id": "file-XFlOqJYTPBPwMZE3IopCBv1Z",
    "mime_type": "image/webp",
    "download_link": "https://files.oaiusercontent.com/file-XFlOqJYTPBPwMZE3IopCBv1Z?se=2024-03-11T20%3A29%3A52Z&sp=r&sv=2021-08-06&sr=b&rscc=max-age%3D31536000%2C%20immutable&rscd=attachment%3B%20filename%3Da580bae6-ea30-478e-a3e2-1f6c06c3e02f.webp&sig=ZPWol5eXACxU1O9azLwRNgKVidCe%2BwgMOc/TdrPGYII%3D"
  },
  {
    "name": "2023 Benefits Booklet.pdf",
    "id": "file-s5nX7o4junn2ig0J84r8Q0Ew",
    "mime_type": "application/pdf",
    "download_link": "https://files.oaiusercontent.com/file-s5nX7o4junn2ig0J84r8Q0Ew?se=2024-03-11T20%3A29%3A52Z&sp=r&sv=2021-08-06&sr=b&rscc=max-age%3D299%2C%20immutable&rscd=attachment%3B%20filename%3D2023%2520Benefits%2520Booklet.pdf&sig=Ivhviy%2BrgoyUjxZ%2BingpwtUwsA4%2BWaRfXy8ru9AfcII%3D"
  }
]

Actions는 사용자가 업로드한 파일, DALL-E가 생성한 이미지, Code Interpreter가 만든 파일을 포함할 수 있어요.

OpenAPI 예시

/createWidget:
  post:
    operationId: createWidget
    summary: Creates a widget based on an image.
    description: Uploads a file reference using its file id. This file should be an image created by DALL·E or uploaded by the user. JPG, WEBP, and PNG are supported for widget creation.
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              openaiFileIdRefs:
                type: array
                items:
                  type: string

이 스키마는 openaiFileIdRefs를 string 타입의 배열로 보여주지만, 런타임에는 앞서 본 것처럼 JSON 객체 배열로 채워져요.

파일 반환하기 (Returning files)

요청은 최대 10개의 파일을 반환할 수 있어요. 각 파일은 최대 10MB이며 이미지나 비디오일 수 없어요.

이 파일들은 사용자가 업로드한 것과 마찬가지로 대화의 일부가 돼요. 즉 code interpreter, file search에서 사용할 수 있고, 이후 액션 호출의 일부로 전송될 수 있어요. 웹 앱에서 사용자는 파일이 반환된 것을 보고 다운로드할 수 있어요.

파일을 반환하려면 응답 본문에 openaiFileResponse 파라미터가 포함되어야 해요. 이 파라미터는 항상 배열이어야 하며, 두 가지 방식 중 하나로 채워져야 해요.

인라인 옵션 (Inline option)

배열의 각 요소는 다음을 포함하는 JSON 객체예요:

name 파일 이름. 사용자에게 보여져요.
mime_type 파일의 MIME 타입. 자격(eligibility)과 어떤 기능이 파일에 접근할 수 있는지를 결정하는 데 사용돼요.
content 파일의 base64 인코딩된 내용.

두 요소를 가진 openaiFileResponse 배열의 예시예요:

[
  {
    "name": "example_document.pdf",
    "mime_type": "application/pdf",
    "content": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyIC9GbGF0ZURlY29kZT4+CnN0cmVhbQpHhD93PQplbmRzdHJlYW0KZW5kb2JqCg=="
  },
  {
    "name": "sample_spreadsheet.csv",
    "mime_type": "text/csv",
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
  }
]

OpenAPI 예시

/papers:
  get:
    operationId: findPapers
    summary: Retrieve PDFs of relevant academic papers.
    description: Provided an academic topic, up to five relevant papers will be returned as PDFs.
    parameters:
      - in: query
        name: topic
        required: true
        schema:
          type: string
        description: The topic the papers should be about.
    responses:
      "200":
        description: Zero to five academic paper PDFs
        content:
          application/json:
            schema:
              type: object
              properties:
                openaiFileResponse:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the file.
                      mime_type:
                        type: string
                        description: The MIME type of the file.
                      content:
                        type: string
                        format: byte
                        description: The content of the file in base64 encoding.

URL 옵션

배열의 각 요소는 다운로드할 파일을 참조하는 URL이에요. 파일 이름과 MIME 타입을 결정할 수 있도록 Content-Disposition 및 Content-Type 헤더를 설정해야 해요. 파일 이름은 사용자에게 보여져요. 파일의 MIME 타입은 자격과 어떤 기능이 파일에 접근할 수 있는지를 결정해요.

각 파일을 가져오는 데는 10초 타임아웃이 있어요.

두 요소를 가진 openaiFileResponse 배열의 예시예요:

[
  "https://example.com/f/dca89f18-16d4-4a65-8ea2-ededced01646",
  "https://example.com/f/01fad6b0-635b-4803-a583-0f678b2e6153"
]

각 URL에 필요한 헤더의 예시예요:

Content-Type: application/pdf
Content-Disposition: attachment; filename="example_document.pdf"

OpenAPI 예시

/papers:
  get:
    operationId: findPapers
    summary: Retrieve PDFs of relevant academic papers.
    description: Provided an academic topic, up to five relevant papers will be returned as PDFs.
    parameters:
      - in: query
        name: topic
        required: true
        schema:
          type: string
        description: The topic the papers should be about.
    responses:
      '200':
        description: Zero to five academic paper PDFs
        content:
            application/json:
              schema:
                type: object
                properties:
                  openaiFileResponse:
                    type: array
                    items:
                      type: string
                      format: uri
                      description: URLs to fetch the files.

더 알아보기 (Learn more)

관련 문서: GPT Actions 인증과 GPT Actions 시작하기를 참고하세요.