Linkfox Multimodal Recognize Image

# 图片识别 API 参考

## 调用规范

- **请求地址**：`https://tool-gateway.linkfox.com/multimodal/recognizeImage`
- **请求方式**：POST，Content-Type: application/json
- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOXAGENT_API_KEY` 读取（如未配置，提示用户前往 https://yxgb3sicy7.feishu.cn/wiki/GIkkweGghiyzkqkRXQKc2n0Tnre 申请）

## 请求参数

POST Body（JSON）：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| imageUrl | string | 是 | 图片地址（仅支持jpg/jpeg/png/gif/webp/bmp格式），最大长度1000字符 |
| requirement | string | 否 | 用户意图，描述需要从图片中识别或分析的内容，默认值为"描述这张图片里面的内容"，最大长度1000字符 |


## 响应结构

| 字段 | 类型 | 说明 |
|------|------|------|
| text | string | 图片分析的文本结果 |
| stdout | string | 标准输出内容 |
| status | string | 响应状态标识 |
| type | string | 组件类型 |
| costToken | integer | 消耗token |

## 错误码

正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。

| errcode | 含义 | 处理建议 |
|---------|------|----------|
| 200 | 成功 | 正常解析业务字段 |
| 401 | 认证失败 | 检查请求头 `Authorization` 是否正确携带 API Key；API Key 申请方式请参考上述[调用规范](#调用规范)下的认证方式。|
| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |

错误响应示例：

```json
{
    "errcode": 401,
    "errmsg": "authorized error"
}
```

## curl 示例

```bash
curl -X POST https://tool-gateway.linkfox.com/multimodal/recognizeImage \
  -H "Authorization: $LINKFOXAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl": "https://example.com/sample-product.jpg", "requirement": "描述这张图片里面的内容并列出关键视觉特征"}'
```

---

## Feedback API

> This endpoint is **separate** from the tool API above. Do not mix the two base URLs.

- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`
- **Content-Type:** `application/json`

```json
{
  "skillName": "linkfox-xxx-xxx",
  "sentiment": "POSITIVE",
  "category": "OTHER",
  "content": "Results were accurate, user was satisfied."
}
```

**Field rules:**
- `skillName`: Use this skill's `name` from the YAML frontmatter
- `sentiment`: Choose ONE — `POSITIVE` (praise), `NEUTRAL` (suggestion without emotion), `NEGATIVE` (complaint or error)
- `category`: Choose ONE — `BUG` (malfunction or wrong data), `COMPLAINT` (user dissatisfaction), `SUGGESTION` (improvement idea), `OTHER`
- `content`: Include what the user said or intended, what actually happened, and why it is a problem or praise


#!/usr/bin/env python3
"""
Multimodal Image Recognition - LinkFox Skill
Calls the multimodal/recognizeImage API endpoint to analyze images.

Usage:
  python multimodal_recognize_image.py '{"imageUrl": "https://example.com/photo.jpg", "requirement": "Describe this image"}'
"""

import json
import os
import sys
from urllib.request import urlopen, Request
from urllib.error import HTTPError, URLError


API_URL = "https://tool-gateway.linkfox.com/multimodal/recognizeImage"

# Supported image formats
SUPPORTED_FORMATS = (".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp")


def get_api_key():
    """Retrieve the API key from environment, with a friendly prompt if missing."""
    key = os.environ.get("LINKFOXAGENT_API_KEY")
    if not key:
        print(
            "API Key not configured. Please complete authorization first:\n"
            "1. Visit https://yxgb3sicy7.feishu.cn/wiki/GIkkweGghiyzkqkRXQKc2n0Tnre to obtain your Key\n"
            "2. Set the environment variable: export LINKFOXAGENT_API_KEY=your-key-here",
            file=sys.stderr,
        )
        sys.exit(1)
    return key


def validate_params(params: dict):
    """Validate request parameters before sending to the API."""
    image_url = params.get("imageUrl")
    if not image_url:
        print("Error: 'imageUrl' is required.", file=sys.stderr)
        sys.exit(1)

    if len(image_url) > 1000:
        print("Error: 'imageUrl' exceeds the maximum length of 1000 characters.", file=sys.stderr)
        sys.exit(1)

    requirement = params.get("requirement", "")
    if requirement and len(requirement) > 1000:
        print("Error: 'requirement' exceeds the maximum length of 1000 characters.", file=sys.stderr)