## 一. 开始使用

调用 BizyAir 标准模型 API 前，请先完成以下准备。

### 1. 注册并充值

登录或注册 BizyAir 账号，并确保充值余额充足。**标准模型 API 使用充值余额付费。**

### 2. 获取您的 API Key

每位用户都拥有 BizyAir 提供的独特 **API Key**。

您可以将光标移动至右上角用户头像处，点击【API 密钥】获取您的专属密钥。

**请妥善保存您的 API Key**，它将参与接下来的每一步操作。

## 二. 提交请求

您现在可以提交 API 请求了。

### 1. 请求示例

请先在运行环境中设置 `BIZYAIR_API_KEY`，再复制并运行对应语言的代码。

在这之前，您可以对代码块中的参数部分进行调整，以精准生成您所需要的内容。

注意：参数设置的格式与要求，请严格参考 **【2. 请求参数说明】**。

```python
import os

import requests

api_key = os.environ["BIZYAIR_API_KEY"]
url = "https://api.bizyair.ai/v1/modelzoo/tasks/openapi/gemini-omni-flash-1-2-official/reference-to-video"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}
payload = {
  "prompt": "Using the reference image as the guide, a dancer in a flowing crimson dress performs beneath warm paper lanterns, sleeves trailing like ribbons, the camera arcing around her in one smooth take as lantern light flickers across silk and cherry petals drift through the velvet air.",
  "ref_images": [
    "https://storage.bizyair.ai/inputs/jnt8ZuQHAJ1gT6h7lt4HIO7z2KJmg5P6.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 8
}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
result = response.json()
if result.get("code") != 20000 or result.get("status") is not True:
    raise RuntimeError(result.get("message") or "BizyAir API request failed")
print(result)
```

提交后，响应里是 `request_id`，结果用第三节的查询接口获取。如果同时加上请求头 "X-Bizyair-Task-WebHook-Url": `https://your-website/webhook`，任务结束时 BizyAir 还会向该地址 POST 结果。例如：

```python
import os

import requests

api_key = os.environ["BIZYAIR_API_KEY"]
webhook_url = os.environ["WEBHOOK_URL"]
webhook_authorization = os.environ["WEBHOOK_AUTHORIZATION"]
webhook_trace_id = os.environ["WEBHOOK_TRACE_ID"]
url = "https://api.bizyair.ai/v1/modelzoo/tasks/openapi/gemini-omni-flash-1-2-official/reference-to-video"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}",
    "X-Bizyair-Task-WebHook-Url": webhook_url,
    "X-Bizyair-Task-Authorization": webhook_authorization,
    "X-Bizyair-Task-Trace-Id": webhook_trace_id
}
payload = {
  "prompt": "Using the reference image as the guide, a dancer in a flowing crimson dress performs beneath warm paper lanterns, sleeves trailing like ribbons, the camera arcing around her in one smooth take as lantern light flickers across silk and cherry petals drift through the velvet air.",
  "ref_images": [
    "https://storage.bizyair.ai/inputs/jnt8ZuQHAJ1gT6h7lt4HIO7z2KJmg5P6.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 8
}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
result = response.json()
if result.get("code") != 20000 or result.get("status") is not True:
    raise RuntimeError(result.get("message") or "BizyAir API request failed")
print(result)
```

是否配置 Webhook，模型请求体参数都相同。需要注意的是请求头：

| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| X-Bizyair-Task-WebHook-Url | string | 选填 | 任务结束后的回调地址。不设置则不发送回调，请用第三节的查询接口主动获取结果。回调地址需使用 HTTP 或 HTTPS，且应接收 POST 请求。若回调地址在海外，BizyAir 不保证回调成功，请悉知。 |
| X-Bizyair-Task-Authorization | string | 选填 | 如回调接口需要鉴权，请把凭据写在这里。它是唯一会被改写的请求头：回调时去掉 `X-Bizyair-Task-` 前缀，以 `Authorization: ${YOUR_WEBHOOK_AUTHORIZATION}` 的形式送达。 |
| X-Bizyair-Task-${HEADER_NAME} | string | 选填 | 除 `X-Bizyair-Task-Authorization` 外，其余以 `X-Bizyair-Task-` 开头的请求头都会连同前缀原样出现在回调请求头中，例如上方示例的 `X-Bizyair-Task-Trace-Id`。 |

### 2. 请求参数说明

您可以阅读以下的【**请求参数说明**】，进一步完善您提交的请求。这会使您最终的运行成功更加准确，但请严格遵守参数内容要求，以免运行失败。

| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| prompt | string | 必填 | 提示词 |
| ref_images | string[] | 选填 | 最多上传数量：9<br/>Ref images |
| ref_videos | string[] | 选填 | 最多上传数量：3<br/>Ref videos |
| aspect_ratio | string | 选填 | ⟨bz_enum_json⟩["16:9","9:16"]⟨/bz_enum_json⟩<br/>缺失时将自动填充默认值：16:9<br/>Aspect ratio |
| resolution | string | 选填 | ⟨bz_enum_json⟩["360p","720p","1080p","4k"]⟨/bz_enum_json⟩<br/>缺失时将自动填充默认值：720p<br/>分辨率 |
| duration | number | 选填 | 取值范围：3 ~ 15<br/>缺失时将自动填充默认值：8<br/>时长 |

> 为保护您的业务敏感信息（如 prompt 设计等），我们支持对 API 调用记录中的指定字段进行脱敏处理。脱敏后的字段在查询调用记录时将显示为 `[调用方要求隐藏]`，但不影响实际请求的执行和计费准确性。
>
> **使用方法**：在请求头中携带 `X-Bizyair-Log-Mask-Fields`，指定需要脱敏的字段，多个字段用英文逗号分隔。
>
> ```http
> Content-Type: application/json
> Authorization: Bearer ${BIZYAIR_API_KEY}
> X-Bizyair-Log-Mask-Fields: prompt, ref_images
> ```

### 3. 响应示例

在成功提交请求后，您会收到类似的信息反馈。

这是一个**异步任务提交的成功回执**，作用是告诉你：“请求已接收，任务正在排队执行中”。

如果您收到了其他的信息反馈，可以结合下文【**4. 响应字段说明**】进一步了解详情。

```json
{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "request_id": "4569bb94-1d30-417a-a987-9715de1e2633"
  }
}
```

### 4. 响应字段说明

您可以阅读下方的【**响应字段说明**】，了解各字段含义与取值说明。

| 参数名 | 类型 | 说明 |
| :--- | :--- | :--- |
| code | integer | 响应状态码，20000 表示成功。 |
| message | string | 接口层面的提示或错误信息。 |
| status | boolean | 接口调用是否成功；与表示任务状态的字符串 data.status 不是同一个字段。 |
| data | object | 响应数据包。 |
| data.request_id | string | 请求ID，用于后续查询任务状态。 |

## 三. 查询结果

在这个阶段，您可以通过刚才产生的**任务单号（request_id）**，去主动查询任务是否完成，以及获取最终结果。

### 1. 请求示例

请在运行环境中设置 `BIZYAIR_API_KEY`，并把示例中的 `request_id` 替换为提交响应返回的任务单号。

```python
import os

import requests

api_key = os.environ["BIZYAIR_API_KEY"]
request_id = "${REQUEST_ID}"
url = f"https://api.bizyair.ai/v1/modelzoo/tasks/openapi/{request_id}"
headers = {
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)
response.raise_for_status()
result = response.json()
if result.get("code") != 20000 or result.get("status") is not True:
    raise RuntimeError(result.get("message") or "BizyAir API request failed")
print(result)
```

### 2. 响应示例

这是一个通过调用 **BizyAir 查询接口**，在任务生成完成、成功生成内容之后，服务器最终返回的结果回执。

也是整个 AI 生图流程的【**最终结果**】。通过浏览这段信息，您可以了解到上述所有操作的最终结果。

如果您收到了其他的信息反馈，可以结合下文【**3. 响应字段说明**】进一步了解详情。

```json
{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "request_id": "4569bb94-1d30-417a-a987-9715de1e2633",
    "status": "Success",
    "message": null,
    "created_at": "2026-04-15T13:32:30Z",
    "executed_at": "2026-04-15T13:32:32Z",
    "ended_at": "2026-04-15T13:42:32Z",
    "outputs": {
      "videos": [
        "https://storage.bizyair.ai/outputs_examples/vJMvyMU2CUKune7iAkocIdkb8QNLIVWp.mp4"
      ]
    },
    "cost_times": {
      "total_cost_time": 600000,
      "inference_duration": 598000
    }
  }
}
```

### 3. 响应字段说明

您可以阅读下方的【**响应字段说明**】，了解各字段含义与取值说明。

| 参数名 | 类型 | 说明 |
| :--- | :--- | :--- |
| code | integer | 响应状态码，20000 表示成功。 |
| message | string | 接口层面的提示或错误信息；任务自身的失败原因见 data.message。 |
| status | boolean | 接口调用是否成功；与表示任务状态的字符串 data.status 不是同一个字段。 |
| data | object | 响应数据包。 |
| data.request_id | string | 请求ID，用于后续查询任务状态。 |
| data.status | string | 任务状态。已确认终态为 Success、Failed；其他状态继续查询。 |
| data.message | string 或 null | 任务为 Failed 时的错误信息；其他状态为 null 或不返回该字段。 |
| data.created_at | string | ISO 8601 UTC 格式的任务创建时间，例如 2026-09-07T07:34:56Z。 |
| data.executed_at | string | ISO 8601 UTC 格式的任务开始执行时间。 |
| data.ended_at | string | ISO 8601 UTC 格式的任务结束时间；部分 Failed 响应可能省略。 |
| data.outputs | object | 输出对象；未完成或无输出时为空对象 {}。 |
| data.outputs.videos | string[] | 视频类输出结果，URL 实际上是文件的下载链接（CDN 地址） |
| data.cost_times | object | 耗时对象；未完成或未记录耗时时为空对象 {}。 |
| data.cost_times.total_cost_time | integer | 任务总耗时，单位毫秒。任务完成后返回。 |
| data.cost_times.inference_duration | integer | 模型推理耗时，单位毫秒。任务完成后返回。 |

> 备注：输出 URL 为 CDN 下载链接，不保证长期可用，请在任务完成后尽快转存到您自己的存储。

### 4. Webhook 回调说明

如果您在创建任务时通过`X-Bizyair-Task-WebHook-Url`请求头指定了 Webhook 回调地址，BizyAir 会在任务结束后，向该地址发送回调通知。

当任务成功时：

```json
{
  "request_id": "6b88a97e-76e8-480a-bae7-a6f7f37b4e97",
  "status": "Success",
  "created_at": "2026-05-22T17:14:07Z",
  "executed_at": "2026-05-22T17:14:07Z",
  "ended_at": "2026-05-22T17:14:44Z",
  "outputs": {
    "videos": [
      "https://storage.bizyair.ai/outputs_examples/vJMvyMU2CUKune7iAkocIdkb8QNLIVWp.mp4"
    ]
  },
  "cost_times": {
    "total_cost_time": 36815,
    "inference_duration": 36090
  }
}
```

当任务失败时：

```json
{
  "request_id": "ee8f5246-77ff-4df7-af62-7c55f311bcb2",
  "status": "Failed",
  "message": "Third-party api response error. No image generated.",
  "created_at": "2026-05-25T13:13:04Z",
  "executed_at": "2026-05-25T13:13:04Z",
  "ended_at": "2026-05-25T13:13:06Z",
  "outputs": {
    "texts": [
      "对不起，我不能提供生成此类内容的图像。"
    ]
  },
  "cost_times": {
    "total_cost_time": 1930
  }
}
```

回调 JSON 的字段在顶层。各字段含义与上方查询结果里 `data` 中的任务字段相同。

## 四. 文件上传

这项操作用于资源上传，支持上传图片、音频、视频等资源至 BizyAir 服务器。

上传后的文件将可以作为输入资源使用到您运行的任务当中：提交成功后，把返回的 URL 填入本接口的媒体参数 `ref_images`。

注意：获取上传凭证走 `https://api.bizyair.ai/v1`，输入资源的提交与查询走元数据服务 `https://meta.bizyair.ai/v1`，两者域名不同属正常。

### 1. 获取上传凭证与参数
调用获取上传凭证接口，服务端会返回本次上传所需的 OSS 信息与临时 STS 凭证。

```python
import os

import requests

api_key = os.environ["BIZYAIR_API_KEY"]
url = "https://api.bizyair.ai/v1/upload/token"
params = {
    "file_name": "example.webp",
    "file_type": "inputs_temp"
}
headers = {
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, params=params, headers=headers)
response.raise_for_status()
result = response.json()
if result.get("code") != 20000 or result.get("status") is not True:
    raise RuntimeError(result.get("message") or "BizyAir API request failed")
print(result)
```

获取凭证响应包含 `data.file.object_key`、STS 凭证以及 `data.storage`：

```json
{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "file": {
      "object_key": "inputs_temp/20260907/example.png",
      "access_key_id": "STS.xxxx",
      "access_key_secret": "xxxx",
      "expiration": "2026-09-07T08:00:00Z",
      "security_token": "xxxx"
    },
    "storage": {
      "endpoint": "https://example-oss-endpoint",
      "bucket": "example-bucket",
      "region": "oss-example-region"
    },
    "access_url": "https://storage.example/inputs_temp/20260907/example.png"
  }
}
```

### 2. 使用阿里云 OSS 简单上传

使用上一步返回的 `endpoint`、`bucket`、`region`、`object_key` 与 STS 凭证将本地文件上传到 OSS。更详细信息参考：[阿里云 OSS 简单上传](https://help.aliyun.com/zh/oss/user-guide/simple-upload)、[BizyAir 上传教程](https://docs.bizyair.ai/cn/api/upload-tutorial.html#oss)。

```python
# pip install alibabacloud-oss-v2
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()
    cfg.region = region[4:] if region.startswith("oss-") else region
    cfg.endpoint = endpoint

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

注意：

- 有些 SDK 需要去掉 `region` 的 `oss-` 前缀，如 `oss-us-east-1` → `us-east-1`。
- 建议同时设置 `region` 与 `endpoint`，以返回的 `endpoint` 为准。

### 3. 提交输入资源
当 OSS 上传成功后，提交本次输入资源，便于后续任务直接引用。

```python
import os

import requests

api_key = os.environ["BIZYAIR_API_KEY"]
url = "https://meta.bizyair.ai/v1/input_resource/commit"
payload = {
    "name": "example.webp",
    "object_key": "inputs_temp/20250911/abc123.webp"
}
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
result = response.json()
if result.get("code") != 20000 or result.get("status") is not True:
    raise RuntimeError(result.get("message") or "BizyAir API request failed")
print(result)
```

提交时必须复用获取凭证响应中的 `data.file.object_key`。提交成功后，将响应中的 `data.url` 写入本接口的媒体参数 `ref_images`：

```json
{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "id": 1711,
    "name": "example.png",
    "ext": ".png",
    "url": "https://storage.example/inputs/20260907/example.png"
  }
}
```

### 4. 查询 inputs 列表（可选）

这项操作可以查询您的查询 inputs 列表，

您可以这样校验上传的内容。

```python
import os

import requests

api_key = os.environ["BIZYAIR_API_KEY"]
url = "https://meta.bizyair.ai/v1/input_resource"
params = {
    "current": 1,
    "page_size": 20
}
headers = {
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, params=params, headers=headers)
response.raise_for_status()
result = response.json()
if result.get("code") != 20000 or result.get("status") is not True:
    raise RuntimeError(result.get("message") or "BizyAir API request failed")
print(result)
```