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

# 输入与输出

> input_values 参数、文件上传、输出文件 URL 与耗时统计

## 输入参数与 Schema

`input_values` 是任务的输入参数对象，键的格式为 `节点ID:节点名.字段名`，值可以是字符串、数字、布尔值等。具体可用字段取决于 `web_app_id` 对应的工作流结构。

### 获取 Schema 的方法

1. 进入 BizyAir AI 应用 页面
2. 点击目标 AI 应用 → 进入详情页
3. 点击左上角 **紫色 API 按钮**
4. 在弹出的 API 调用窗口中查看 `input_values` 的完整字段与示例值
5. 切换到 **Shell (curl)** 标签可直接复制完整调用代码

### 常见字段模式

| 字段类型      | 示例 key                                      | 说明             |
| --------- | ------------------------------------------- | -------------- |
| 文本提示词     | `84:CLIPTextEncode.text`                    | 文生图 / 图生图的主提示词 |
| 随机种子      | `88:KSampler.seed`                          | 控制结果可复现性       |
| 图像宽度      | `81:EmptySD3LatentImage.width`              | 输出图宽           |
| 图像高度      | `81:EmptySD3LatentImage.height`             | 输出图高           |
| 采样步数      | `2:BizyAir_BasicScheduler.steps`            | 采样器步数          |
| LLM 用户提示词 | `4:BizyAirSiliconCloudLLMAPI.user_prompt`   | LLM 节点的用户输入    |
| LLM 系统提示词 | `4:BizyAirSiliconCloudLLMAPI.system_prompt` | LLM 节点的系统提示    |

## 文件上传

当工作流需要图片、音频、视频作为输入时（如图生图、图生视频），需先将文件上传到 BizyAir OSS，获得 `url` 后再作为 `input_values` 字段值传入。

### 步骤 1：获取上传凭证

```bash theme={null}
curl -G "https://api.bizyair.ai/x/v1/upload/token" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  --data-urlencode "file_name=example.webp" \
  --data-urlencode "file_type=inputs"
```

响应：

```json theme={null}
{
  "code": 20000, "message": "Ok", "status": true,
  "data": {
    "file": {
      "object_key": "inputs/20250911/abc123.webp",
      "access_key_id": "STS.xxxx",
      "access_key_secret": "xxxx",
      "security_token": "xxxx"
    },
    "storage": {
      "endpoint": "oss-cn-shanghai.aliyuncs.com",
      "bucket": "bizyair-prod",
      "region": "oss-cn-shanghai"
    }
  }
}
```

<Note>
  `file_name` 必须包含扩展名，服务端据此判断文件类型。返回的 STS 凭证为**临时凭证**，请勿长期保存或暴露在前端。
</Note>

### 步骤 2：上传文件到阿里云 OSS

使用返回的凭证将文件直接 PUT 到 OSS。详见 [阿里云 OSS 简单上传](https://help.aliyun.com/zh/oss/simple-upload)。

**Python 示例**：

```python theme={null}
import os
import alibabacloud_oss_v2 as oss

def upload_to_oss(region, endpoint, bucket, object_key, file_path,
                  access_key_id, access_key_secret, security_token):
    os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"] = access_key_id
    os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"] = access_key_secret
    os.environ["ALIBABA_CLOUD_SECURITY_TOKEN"] = security_token

    cfg = oss.config.load_default()
    cfg.credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    normalized_region = region[4:] if region.startswith("oss-") else region
    cfg.region = normalized_region
    cfg.endpoint = endpoint or f"oss-{normalized_region}.aliyuncs.com"

    client = oss.Client(cfg)
    return client.put_object_from_file(
        oss.PutObjectRequest(bucket=bucket, key=object_key),
        file_path
    )
```

**Node.js 示例**：

```javascript theme={null}
const OSS = require("ali-oss");

async function uploadToOss({region, endpoint, bucket, objectKey, filePath,
                            accessKeyId, accessKeySecret, securityToken}) {
  const normalizedRegion = region.startsWith("oss-") ? region.slice(4) : region;
  const client = new OSS({
    region: normalizedRegion,
    endpoint: endpoint || `oss-${normalizedRegion}.aliyuncs.com`,
    accessKeyId, accessKeySecret, stsToken: securityToken, bucket,
  });
  return await client.put(objectKey, filePath);
}
```

### 步骤 3：提交输入资源

OSS 上传成功后，调用 `commit` 接口注册文件，获得可被工作流引用的 `url`。

```bash theme={null}
curl -X POST "https://api.bizyair.ai/x/v1/input_resource/commit" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.webp",
    "object_key": "inputs/20250911/abc123.webp"
  }'
```

响应：

```json theme={null}
{
  "code": 20000, "message": "Ok", "status": true,
  "data": {
    "id": 1711,
    "name": "example.webp",
    "ext": ".webp",
    "url": "https://storage.bizyair.ai/inputs/20250911/abc123.webp"
  }
}
```

返回的 `url` 即可作为 `input_values` 中相应字段的值，传入任务创建接口。

### 可选：查询已上传文件列表

```bash theme={null}
curl -G "https://api.bizyair.ai/x/v1/input_resource" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  --data-urlencode "current=1" \
  --data-urlencode "page_size=20"
```

支持 `current` / `page_size` / `ext` / `object_key` 查询参数。

## 输出文件与对象 URL

任务成功完成后，`outputs[].object_url` 提供结果文件的临时下载链接：

* 域名：`https://storage.bizyair.ai/outputs/...`
* 默认有效期：**15 天**（响应中的 `expired_at` 字段会给出精确时间）
* 过期后**无法恢复**

<Tip>
  生产环境建议在拿到 `object_url` 后立即下载到自有对象存储（OSS / S3），避免链接过期。
</Tip>

## 任务耗时统计

任务结果中包含 `cost_times` 对象，提供各阶段详细耗时（单位：毫秒）：

| 字段                       | 说明                   |
| ------------------------ | -------------------- |
| `inference_cost_time`    | 纯推理耗时                |
| `running_cost_time`      | 运行总耗时（含推理 + 节点切换）    |
| `total_cost_time`        | 任务总耗时（含排队 + 准备 + 运行） |
| `real_cpu_cost_time`     | 实际 CPU 耗时            |
| `real_gpu_cost_time`     | 实际 GPU 耗时            |
| `real_total_cost_time`   | 实际总耗时                |
| `real_bizyair_cost_time` | 内部系统实际处理耗时           |

<Note>
  计费仅基于 `inference_cost_time`（推理部分），其他阶段免费。
</Note>