## 一. 开始使用

调用 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/video-edit"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}
payload = {
  "prompt": "Regrade the footage toward a moody thriller look: shadows pushed to cool teal, highlights to warm amber, gentle contrast lift with fine 35mm grain, skin tones kept warm and natural while frame edges gain a subtle dark vignette.",
  "video_urls": [
    "https://storage.bizyair.ai/inputs/eEbmO0StlUD2o3YRSmOVevu6HRb3BL2b.mp4"
  ],
  "resolution": "720p"
}

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/video-edit"
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": "Regrade the footage toward a moody thriller look: shadows pushed to cool teal, highlights to warm amber, gentle contrast lift with fine 35mm grain, skin tones kept warm and natural while frame edges gain a subtle dark vignette.",
  "video_urls": [
    "https://storage.bizyair.ai/inputs/eEbmO0StlUD2o3YRSmOVevu6HRb3BL2b.mp4"
  ],
  "resolution": "720p"
}

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 | 必填 | 提示词 |
| video_urls | string[] | 必填 | 最多上传数量：1<br/>Video urls |
| resolution | string | 选填 | ⟨bz_enum_json⟩["360p","720p","1080p","4k"]⟨/bz_enum_json⟩<br/>缺失时将自动填充默认值：720p<br/>分辨率 |

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

### 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/mmmTdqIjVpAGLnmfqsLWXL70B1YhROLs.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/mmmTdqIjVpAGLnmfqsLWXL70B1YhROLs.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 填入本接口的媒体参数 `video_urls`。

注意：获取上传凭证走 `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` 写入本接口的媒体参数 `video_urls`：

```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)
```