> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiid.edu.kg/llms.txt
> Use this file to discover all available pages before exploring further.

# 建立回應 (OpenAI Responses API)

> OpenAI Responses API，用於建立模型回應。
支援多輪對話、工具呼叫、推理等功能。

補充 OpenAI Responses API 的圖片生成非同步用例。`background=true` 用於提交背景任務，建立介面會立即回傳 `status=queued` 和完整 `id`，隨後使用該 `id` 呼叫 `GET /v1/responses/{response_id}` 查詢結果。

## 非同步圖片生成流程

1. 呼叫 `POST /v1/responses`，請求體中傳入 `tools=[{ "type": "image_generation" }]` 且 `background=true`。
2. 保存建立介面回傳的完整 `id`，例如 `resp_xxx`。不要截斷、重寫或只保存 `metadata.task_id`。
3. 呼叫 `GET /v1/responses/{response_id}` 查詢，直到 `status=completed` 或 `status=failed`。
4. 成功後讀取 `output[].url` 取得圖片連結。

### 建立非同步圖片任務範例

```http
POST /v1/responses
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2-2k",
  "input": "生成一张 2K 横屏产品海报，白色运动鞋，干净棚拍光线，高级商业摄影风格。",
  "stream": false,
  "tools": [
    {
      "type": "image_generation"
    }
  ],
  "background": true
}
```

建立介面回傳範例：

```json
{
  "id": "resp_xxx",
  "created_at": 1780649146,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {
    "task_id": "010c31178d26436ca6194cde07931b33"
  },
  "model": "gpt-image-2-2k",
  "object": "response",
  "output": [],
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": null,
  "tools": null,
  "top_p": null,
  "max_output_tokens": null,
  "previous_response_id": null,
  "reasoning": null,
  "status": "queued",
  "text": null,
  "truncation": null,
  "usage": null,
  "user": null,
  "store": null
}
```

支援模型：`gpt-image-2-2k`、`gpt-image-2-4k`、`nano-banana-pro`。



## OpenAPI

````yaml api-reference/zh-tw/openapi.json POST /v1/responses
openapi: 3.0.0
info:
  title: 出海營 API 參考文件
  version: 1.0.0
  description: Public AI Gateway API Reference
servers:
  - url: https://api.aiid.edu.kg
security:
  - BearerAuth: []
tags:
  - name: OpenAI格式（Chat）
  - name: OpenAI格式（Responses）
  - name: 圖片生成 Gemini 格式
  - name: 圖片生成OpenAI DALL-E 格式
  - name: 獲取模型列表
  - name: 影片生成HappyHorse與 Wan
  - name: 影片生成Kling格式
  - name: 影片生成 Omni 與 Veo 格式
  - name: 影片生成 Seedance 格式
  - name: 影片生成Sora相容格式
  - name: 影片生成 Vidu 格式
  - name: 音樂生成任務格式
paths:
  /v1/responses:
    post:
      tags:
        - OpenAI格式（Responses）
      summary: 建立回應 (OpenAI Responses API)
      description: >-
        OpenAI Responses API，用於建立模型回應。

        支援多輪對話、工具呼叫、推理等功能。


        補充 OpenAI Responses API 的圖片生成非同步用例。`background=true` 用於提交背景任務，建立介面會立即回傳
        `status=queued` 和完整 `id`，隨後使用該 `id` 呼叫 `GET /v1/responses/{response_id}`
        查詢結果。


        ## 非同步圖片生成流程


        1. 呼叫 `POST /v1/responses`，請求體中傳入 `tools=[{ "type": "image_generation"
        }]` 且 `background=true`。

        2. 保存建立介面回傳的完整 `id`，例如 `resp_xxx`。不要截斷、重寫或只保存 `metadata.task_id`。

        3. 呼叫 `GET /v1/responses/{response_id}` 查詢，直到 `status=completed` 或
        `status=failed`。

        4. 成功後讀取 `output[].url` 取得圖片連結。


        ### 建立非同步圖片任務範例


        ```http

        POST /v1/responses

        Content-Type: application/json

        ```


        ```json

        {
          "model": "gpt-image-2-2k",
          "input": "生成一张 2K 横屏产品海报，白色运动鞋，干净棚拍光线，高级商业摄影风格。",
          "stream": false,
          "tools": [
            {
              "type": "image_generation"
            }
          ],
          "background": true
        }

        ```


        建立介面回傳範例：


        ```json

        {
          "id": "resp_xxx",
          "created_at": 1780649146,
          "error": null,
          "incomplete_details": null,
          "instructions": null,
          "metadata": {
            "task_id": "010c31178d26436ca6194cde07931b33"
          },
          "model": "gpt-image-2-2k",
          "object": "response",
          "output": [],
          "parallel_tool_calls": true,
          "temperature": null,
          "tool_choice": null,
          "tools": null,
          "top_p": null,
          "max_output_tokens": null,
          "previous_response_id": null,
          "reasoning": null,
          "status": "queued",
          "text": null,
          "truncation": null,
          "usage": null,
          "user": null,
          "store": null
        }

        ```


        支援模型：`gpt-image-2-2k`、`gpt-image-2-4k`、`nano-banana-pro`。
      operationId: createResponse
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
              properties: {}
            examples:
              responses_image_async:
                summary: 圖片生成非同步
                value:
                  model: gpt-image-2-2k
                  input: 生成一张 2K 横屏产品海报，白色运动鞋，干净棚拍光线，高级商业摄影风格。
                  stream: false
                  tools:
                    - type: image_generation
                  background: true
        required: true
      responses:
        '200':
          description: 成功建立回應
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
              examples:
                responses_image_async_queued:
                  summary: 圖片生成非同步建立返回
                  value:
                    id: resp_xxx
                    created_at: 1780649146
                    error: null
                    incomplete_details: null
                    instructions: null
                    metadata:
                      task_id: 010c31178d26436ca6194cde07931b33
                    model: gpt-image-2-2k
                    object: response
                    output: []
                    parallel_tool_calls: true
                    temperature: null
                    tool_choice: null
                    tools: null
                    top_p: null
                    max_output_tokens: null
                    previous_response_id: null
                    reasoning: null
                    status: queued
                    text: null
                    truncation: null
                    usage: null
                    user: null
                    store: null
          headers: {}
      deprecated: false
      security:
        - BearerAuth: []
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
        input:
          description: 輸入內容，可以是字串或訊息陣列
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties: {}
        instructions:
          type: string
        max_output_tokens:
          type: integer
        temperature:
          type: number
        top_p:
          type: number
        stream:
          type: boolean
        tools:
          type: array
          items:
            type: object
            properties: {}
        tool_choice:
          oneOf:
            - type: string
            - type: object
              properties: {}
        reasoning:
          type: object
          properties:
            effort:
              type: string
              enum:
                - low
                - medium
                - high
            summary:
              type: string
        previous_response_id:
          type: string
        truncation:
          type: string
          enum:
            - auto
            - disabled
    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        created_at:
          type: integer
        status:
          type: string
          enum:
            - completed
            - failed
            - in_progress
            - incomplete
        model:
          type: string
        output:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              id:
                type: string
              status:
                type: string
              role:
                type: string
              content:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    text:
                      type: string
        usage:
          $ref: '#/components/schemas/Usage'
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: 提示詞 Token 數
        completion_tokens:
          type: integer
          description: 補全 Token 數
        total_tokens:
          type: integer
          description: 總 Token 數
        prompt_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
            text_tokens:
              type: integer
            audio_tokens:
              type: integer
            image_tokens:
              type: integer
        completion_tokens_details:
          type: object
          properties:
            text_tokens:
              type: integer
            audio_tokens:
              type: integer
            reasoning_tokens:
              type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |-
        使用 Bearer Token 認證。
        格式: `Authorization: Bearer sk-xxxxxx`

````