# see2ai_media_url_health_check_v1

> SEE2AI 媒体链接探活：HEAD（必要时降级为短 Range GET）检查公网视频/图片/音频 URL 是否真的可访问、可分段播放。当用户对已生成的 mp4/png/mp3 等资源报告「打不开」类问题，agent **必须**先调用本 skill 再判断是否需要重新生成；若返回 ok=true，应直接告知用户换浏览器 / 复制链接 / 长按下载，禁止重新调用付费的 video / image / audio 生成 skill。

## 📖 接入指引

**Endpoint**: `POST /api/v1/actions/see2ai_media_url_health_check_v1`

**认证方式**: Bearer Token (租户 API Key)

### Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/v1/actions/see2ai_media_url_health_check_v1` | Submit the standard action request. |

> **⚠️ 重要提示**
> 
> 本 API 是 SEE2AI 平台标准化封装后的接口，**参数格式与任何上游 API 不同**。
> 请直接使用下方 Schema 中定义的参数，无需参考其他文档。
> 
> *例如：*
> *- 文本模型参数可能是 `query` 而不是 `messages` 数组*
> *- 视频模型参数可能是 `brief` (创意简报) 而不是复杂的配置项*

## 📥 输入参数 (Input Schema)

```json
{
  "properties": {
    "url": {
      "description": "待探活的公网媒体 URL（http/https）。当用户报告「我点不开 / 打不开 / 加载失败 / 链接坏了」类问题、且对应的媒体是本平台先前生成 / 上传的资源时，agent **必须**先调用本 skill 再决定是否重新生成 — 若 ok=true 直接告知用户换浏览器 / 复制链接 / 长按下载，禁止调 video / image / audio 重新生成。",
      "title": "Url",
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "title": "MediaUrlHealthCheckInput",
  "type": "object"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `url` | string | ✅ 是 | `-` | 待探活的公网媒体 URL（http/https）。当用户报告「我点不开 / 打不开 / 加载失败 / 链接坏了」类问题、且对应的媒体是本平台先前生成 / 上传的资源时，agent **必须**先调用本 skill 再决定是否重新生成 — 若 ok=true 直接告知用户换浏览器 / 复制链接 / 长按下载，禁止调 video / image / audio 重新生成。 |

## 📤 输出结果 (Output Schema)

```json
{
  "properties": {
    "input_tokens": {
      "default": 0,
      "description": "输入消耗的词元数量",
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "default": 0,
      "description": "输出消耗的词元数量",
      "title": "Output Tokens",
      "type": "integer"
    },
    "total_tokens": {
      "default": 0,
      "description": "总消耗的词元数量",
      "title": "Total Tokens",
      "type": "integer"
    },
    "model": {
      "default": "",
      "description": "实际使用的 SEE2AI 化身模型名称（由各 action 显式填写）",
      "title": "Model",
      "type": "string"
    },
    "source": {
      "default": "see2ai",
      "description": "服务来源（统一 `see2ai`；真实路由仅平台内部可见）",
      "title": "Source",
      "type": "string"
    },
    "cost_points": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算）",
      "title": "Cost Points"
    },
    "ok": {
      "default": false,
      "description": "探活是否通过（HTTP 2xx + 拿到合理的 Content-Type）",
      "title": "Ok",
      "type": "boolean"
    },
    "status_code": {
      "default": 0,
      "description": "HEAD 请求的 HTTP 状态码",
      "minimum": 0,
      "title": "Status Code",
      "type": "integer"
    },
    "content_type": {
      "default": "",
      "description": "Content-Type 头（如 'video/mp4'）",
      "title": "Content Type",
      "type": "string"
    },
    "content_length": {
      "default": 0,
      "description": "Content-Length 头（字节）；未知或不返回则 0",
      "minimum": 0,
      "title": "Content Length",
      "type": "integer"
    },
    "accept_ranges": {
      "default": false,
      "description": "服务器是否支持 Range 请求（视频分段播放体验的关键）",
      "title": "Accept Ranges",
      "type": "boolean"
    },
    "notes": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "非阻断提示（如 mime 类型不在常见媒体白名单、Range 不支持、HEAD 拒绝降级用 GET 等）",
      "title": "Notes"
    }
  },
  "title": "MediaUrlHealthCheckOutput",
  "type": "object"
}
```

### 输出字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `input_tokens` | integer | 输入消耗的词元数量 |
| `output_tokens` | integer | 输出消耗的词元数量 |
| `total_tokens` | integer | 总消耗的词元数量 |
| `model` | string | 实际使用的 SEE2AI 化身模型名称（由各 action 显式填写） |
| `source` | string | 服务来源（统一 `see2ai`；真实路由仅平台内部可见） |
| `cost_points` | integer / null | 预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算） |
| `ok` | boolean | 探活是否通过（HTTP 2xx + 拿到合理的 Content-Type） |
| `status_code` | integer | HEAD 请求的 HTTP 状态码 |
| `content_type` | string | Content-Type 头（如 'video/mp4'） |
| `content_length` | integer | Content-Length 头（字节）；未知或不返回则 0 |
| `accept_ranges` | boolean | 服务器是否支持 Range 请求（视频分段播放体验的关键） |
| `notes` | array / null | 非阻断提示（如 mime 类型不在常见媒体白名单、Range 不支持、HEAD 拒绝降级用 GET 等） |

## 💡 调用示例

### cURL 示例

```bash
curl -X POST "https://see2ai.com/api/v1/actions/see2ai_media_url_health_check_v1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-your-tenant-api-key" \
     -d '{
  "url": "https://example.com/video.mp4"
}'
```

### Python 示例

```python
import requests

API_KEY = "sk-your-tenant-api-key"
ENDPOINT = "https://see2ai.com/api/v1/actions/see2ai_media_url_health_check_v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
  "url": "https://example.com/video.mp4"
}

response = requests.post(ENDPOINT, json=payload, headers=headers)
result = response.json()

print(f"结果：{result}")
```

## 💰 计费说明

> 免费（探活）

**注意**: 所有费用都以词元为单位，系统会自动从租户余额中扣除。

## ⚠️ 常见错误码

| HTTP 状态码 | 错误原因 | 解决方案 |
| --- | --- | --- |
| `422` | url 格式错误（必须 http/https） | 检查请求参数是否符合 Schema 要求 |
| `504` | 探活请求超时 | 请稍后重试 |

## 📞 技术支持

- **文档问题**: 查看 [SEE2AI 官方文档](https://see2ai.com/docs)
- **API 状态**: 访问 [服务状态页面](https://see2ai.com/status)
- **问题反馈**: 联系技术支持团队

---

**API 版本**: see2ai_media_url_health_check_v1
**最后更新**: 2026-03-23