dify/web/app/components/develop/template/template.zh.mdx

import { CodeGroup } from '../code.tsx'
import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx'

# 文本生成型应用 API

可用于生成高质量文本的应用，例如生成文章、摘要、翻译等，通过调用 completion-messages 接口，发送用户输入得到生成文本结果。用于生成文本的模型参数和提示词模版取决于开发者在 Dify 提示词编排页的设置。

<div>
  ### 鉴权

  Dify Service API 使用 `API-Key` 进行鉴权。

  建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。

  所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示：

  <CodeGroup title="Code">
    ```javascript
      Authorization: Bearer {API_KEY}

    ```
  </CodeGroup>
</div>

---

<Heading
  url='/completion-messages'
  method='POST'
  title='创建文本补全消息'
  name='#Create-Completion-Message'
/>
<Row>
  <Col>
    创建文本补全消息，支持一问一答模式。

    ### Request Body

    <Properties>
      <Property name='inputs' type='object' key='inputs'>
        （选填）以键值对方式提供用户输入字段，与提示词编排中的变量对应。Key 为变量名称，Value 是参数值。如果字段类型为 Select，传入的 Value 需为预设选项之一。
        <ul>
         {!!props.variables.length && props.variables.map(
            val => (
                <SubProperty name={val.key} type={val.type} key={val.key}>
                  {val.name ? `${val.name}` : ''}
                </SubProperty>
            )
        )}
        </ul>
      </Property>
      <Property name='response_mode' type='string' key='response_mode'>
        - blocking 阻塞型，等待执行完毕后返回结果。（请求若流程较长可能会被中断）
        - streaming 流式返回。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现流式返回。
      </Property>
      <Property name='user' type='string' key='user'>
        用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
      </Property>
      <Property name='files' type='array[object]' key='files'>
          上传的文件。
          - `type` 文件类型:目前仅支持 `image`。
          - `transfer_method` 传递方式:
            - `remote_url`: 图片地址。
            - `local_file`: 上传文件。
          - `upload_file_id` 上传文件 ID。`transfer_method` 为 `local_file` 时必填。
          - `url` 图片地址。`transfer_method` 为 `remote_url` 时必填。
      </Property>
    </Properties>
  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="POST" label="/completion-messages" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/completion-messages' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n    "inputs": ${JSON.stringify(props.inputs)},\n    "response_mode": "streaming",\n    "user": "abc-123"\n}'\n`}>

    ```bash {{ title: 'cURL' }}
    curl --location --request POST '${props.appDetail.api_base_url}/completion-messages' \
    --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "inputs": {},
        "response_mode": "streaming",
        "user": "abc-123"
    }'
    ```

    </CodeGroup>
    ### blocking
    <CodeGroup title="Response">
    ```json {{ title: 'Response' }}
    {
      "id": "0b089b9a-24d9-48cc-94f8-762677276261",
      "answer": "how are you?",
      "created_at": 1679586667
    }
    ```
    </CodeGroup>
    ### streaming
    <CodeGroup title="Response">
    ```streaming {{ title: 'Response' }}
      data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
      data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
    ```
    </CodeGroup>
  </Col>
</Row>

---

<Heading
  url='/messages/{message_id}/feedbacks'
  method='POST'
  title='消息反馈（点赞）'
  name='#feedbacks'
/>
<Row>
  <Col>
    代表最终用户对返回消息进行评价，可以点赞与点踩，该数据将在“日志与标注”页中可见，并用于后续的模型微调。

    ### Path Params

    <Properties>
      <Property name='message_id' type='string' key='message_id'>
        消息 ID
      </Property>
    </Properties>

    ### Request Body

    <Properties>
      <Property name='rating' type='string' key='rating'>
       like 或 dislike， 空值为撤销
      </Property>
      <Property name='user' type='string' key='user'>
        用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
      </Property>
    </Properties>
  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="POST" label="/messages/{message_id}/feedbacks" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/messages/{message_id}/feedbacks \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--header 'Content-Type: application/json' \\\n --data-raw '{ \n "rating": "like",\n    "user": "abc-123"\n}'`}>

    ```bash {{ title: 'cURL' }}
    curl --location --request POST '${props.appDetail.api_base_url}/messages/{message_id}/feedbacks' \
    --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "rating": "like",
        "user": "abc-123"
    }'
    ```

    </CodeGroup>

    <CodeGroup title="Response">
    ```json {{ title: 'Response' }}
    {
      "has_more": false,
      "data": [
        {
          "id": "WAz8eIbvDR60rouK",
          "username": "FrankMcCallister",
          "phone_number": "1-800-759-3000",
          "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
          "display_name": null,
          "conversation_id": "xgQQXg3hrtjh7AvZ",
          "created_at": 692233200
        },
        {
          "id": "hSIhXBhNe8X1d8Et"
          // ...
        }
      ]
    }
    ```
    </CodeGroup>
  </Col>
</Row>

---

<Heading
  url='/files/upload'
  method='POST'
  title='上传文件'
  name='#files-upload'
/>
<Row>
  <Col>
    上传文件到服务器，供文本生成、对话使用。上传的文件仅供当前终端用户使用。

    ### Request Body
    请求方式为 `multipart/form-data`。
    <Properties>
      <Property name='file' type='file' key='file'>
        要上传的文件。目前支持 png, jpg, jpeg, webp, gif 格式文件。
      </Property>
      <Property name='user' type='string' key='user'>
        用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
      </Property>
    </Properties>
  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="POST" label="/files/upload" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/files/upload' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif] \\\n--form 'user=abc-123'`}>

    ```bash {{ title: 'cURL' }}
    curl --location --request POST '${props.appDetail.api_base_url}/files/upload' \
    --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
    --form 'file=@"/path/to/file"'
    ```

    </CodeGroup>

    <CodeGroup title="Response">
    ```json {{ title: 'Response' }}
    {
      "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",  
      "name": "example.png",
      "size": 1024,
      "extension": "png",
      "mime_type": "image/png",
      "created_by": 123,  
      "created_at": 1577836800,
    }
    ```
    </CodeGroup>
  </Col>
</Row>

---

<Heading
  url='/parameters'
  method='GET'
  title='获取应用配置信息'
  name='#parameters'
/>
<Row>
  <Col>
    内容包括：
    1. 已配置的 Input 参数，包括变量名、字段名称、类型与默认值。通常用于客户端加载后显示这些字段的表单或填入默认值。
    2. 上传图片的配置，包括是否开启上传图片，上传图片的数量和上传方式。注意：这个配置只有使用支持多模态的模型时才会生效。

    ### Query

    <Properties>
      <Property name='user' type='string' key='user'>
        用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
      </Property>
    </Properties>
  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="GET" label="/parameters" targetCode={`curl --location --request GET '${props.appDetail.api_base_url}/parameters?user=abc-123' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'`}>

    ```bash {{ title: 'cURL' }}
    curl --location --request GET '${props.appDetail.api_base_url}/parameters?user=abc-123' \
    --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'
    ```

    </CodeGroup>

    <CodeGroup title="Response">
    ```json {{ title: 'Response' }}
    {
      "introduction": "nice to meet you",
      "user_input_form": [
        {
          "text-input": {
            "label": "a",
            "variable": "a",
            "required": true,
            "max_length": 48,
            "default": ""
          }
        }
        {
          // ...
        }
      ],
      "file_upload": {
        "image": {
          "enabled": true,
          "number_limits": 3,
          "transfer_methods": [
            "remote_url",
            "local_file"
          ]
        }
      }
    }
    ```
    </CodeGroup>
  </Col>
</Row>