# OpenAPIClient-php

碳丝路数据开放平台

更多信息，请访问[https://open.tsl3060.com/team](https://open.tsl3060.com/team).

## 安装与使用

### 要求

PHP 7.4 及更高版本。
还应该与 PHP 8.0 一起使用。

### Composer

要通过 [Composer](https:getcomposer.org) 安装绑定，请将以下内容添加到 `composer.json` 中:

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://git.tsl3060.com/tsl3060/low-carbon-platform.git"
    }
  ],
  "require": {
    "tsl3060/low-carbon-platform": "*@dev"
  }
}
```

然后运行 `composer install`

### 手动安装

下载文件并包含 `autoload.php`:

```php
<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');
```

## 入门

### 快速开始

初始化基础配置并调用api示例伪代码:
（调用api端点具体参照[**API端点文档**](README.md#api端点文档)）

```php
function example()
{
    // 基础配置
    $config = new Configuration();
    // 设置appId
    $config->setAppid("your appId");
    // 配置证书
    $config->setPrivateKey(file_get_contents(__DIR__ . "your private key certs path"));
    $config->setPublicKey(file_get_contents(__DIR__ . "your public key certs path"));
    $config->setApiPublicKey(file_get_contents(__DIR__ . "your API public key certs path"));
    // 访问服务路径 根据实际环境设置
    $config->setHost("https://opendev.tsl3060.com");

    // 调用端点api示例 （调用api端点具体参照API端点文档）
    $api = new ExampleApi($config);
    // 设置请求参数
    $param = new ExampleParams();
    $param->setValue("exampleValue");
    // 发送请求
    $result = $api->auth($param);
    print_r($result);
}
```


### 流式调用API使用
```php
    /**
     * 语音转文字
     * @throws ApiException
     */
    public function speechToTextDemo()
    {
        // 获取完成基础配置的配置对象
        $config = ...;
        // 创建流式API调用客户端
        $streamClient = new StreamApiClient($config);
        // 获取二进制流数据（必须是16k采样率的音频二进制数据）
        $binaryData = ...;
        if ($binaryData) {
            // 传入二进制流数据和StreamResponseHandler子类实例
            $streamClient->speechToText($binaryData, new class() extends StreamResponseHandler {
                // 必须重写对应处理器的方法，实时处理返回的文本
                public function speechToTextHandle(SpeechResult $result): void
                {
                    echo "result: "
                        // 文本内容
                        . $result->getText() . "-"
                        // 句子是否结束（每句结束前，之前的内容可能会被修正）
                        . ($result->getSentenceEnd() ? "true" : "false") . "-"
                        // 句子对应音频的开始时间
                        . $result->getBeginTime() . "-"
                        // 句子对应音频的结束时间（如果句子没有结束EndTime为null）
                        . $result->getEndTime() . "\n";
                }
            });
        }
    }

    /**
     * 语音合成
     * @throws ApiException
     */
    public function testTextToSpeech()
    {
        // 获取完成基础配置的配置对象
        $config = ...;
        // 创建流式API调用客户端
        $streamClient = new StreamApiClient($config);
        // 语音合成参数
        $param = new SynthesizerParam();
        // 需要转换的文本
        $param->setText("你好，我的名字叫知楠。");
        // 声音模型可选值参考地址：https://help.aliyun.com/zh/dashscope/developer-reference/model-list-old-version
        $param->setModel("sambert-zhinan-v1");
        // 可选值wav、mp3,默认mp3
        // $param->setFormat("mp3");

        // 传入语音合成参数和StreamResponseHandler子类实例
        $streamClient->synthesizer($param, new class() extends StreamResponseHandler {
            // 必须重写对应处理器的方法，实时处理返回的二进制流
            public function synthesizerHandle(string $result): void
            {
                // 示例：将二进制流保存到文件
                $filePath = '.../temp.mp3';
                $file = fopen($filePath, 'ab');
                if ($file === false) {
                    die('无法打开文件');
                }
                fwrite($file, $result);
                fclose($file);
            }
        });
    }
```

## API端点文档

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*AiApi* | [**chat**](docs/Api/AiApi.md#chat) | **POST** /v1/ai/chat | 元梦ai-对话

## 模型文档

- [ChatParam](docs/Model/ChatParam.md)
- [ChatResult](docs/Model/ChatResult.md)
- [ResponseOpenAPIChatResult](docs/Model/ResponseOpenAPIChatResult.md)
- [SpeechResult](docs/Model/SpeechResult.md)
- [StreamModule](docs/Model/StreamModule.md)
- [SynthesizerParam](docs/Model/SynthesizerParam.md)

## 测试

要运行测试，请使用:

```bash
composer install
vendor/bin/phpunit
```

## 关于

- API version: `0.4.8`
    - Package version: `1.0`