---
name: url2pic-api
description: This skill should be used when needing to extract images or videos from Douyin, Kuaishou, or Xiaohongshu share links, WeChat Official Account articles, or Doubao / Qianwen AI share pages via the URL2PIC (抓取大师) v3 API. It covers request signing, the unified /go endpoint, type mapping by URL, response parsing, and batch ZIP packaging through the job center.
---

# URL2PIC (抓取大师) v3 API Skill

抓取大师提供统一的 v3 抓取接口，输入网页 / APP 分享链接，返回图片或视频地址数组。本技能描述如何鉴权、调用、解析响应。

## 1. 基础信息

- 站点：https://url2pic.php127.com
- API 根：https://url2pic.php127.com/api
- 统一抓取入口：`POST /api/v3/go`
- 任务中心（打包下载）：`POST /api/v2/job-center/submit`、`POST /api/v2/job-center/list`
- 内容类型：`application/json`

## 2. 鉴权

所有需登录的接口都要同时携带：

1. **请求体签名 Sign**：`Sign = md5(JSON.stringify(body)).slice(0, 10)`（即请求体 JSON 字符串的 MD5 前 10 位），放入请求头 `Sign`。
2. **身份凭证**（二选一，优先 Key）：
   - `Key`：用户 API Key（在会员中心「API Key」页面生成 / 重置，长期有效）。
   - `Token`：登录返回的会话 Token（有过期时间）。

未携带或无效时返回 `code=10001/10002`，提示需要登录。

### 示例请求头

```
Content-Type: application/json
Key: u2p5f582fxxxxxxxxxc49a50dbda
Sign: 3a8ee6a1b2
```

## 3. 统一抓取入口 POST /api/v3/go

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 是 | 前端入口类型，见下表 |
| urls | string \| string[] | 是 | 一或多个链接，多个用换行或数组传入，最多 10 个 |

### type 取值

| type | 说明 | 适用链接 |
|------|------|----------|
| `web` | 通用网页图片提取 | 任意网页 |
| `mp-weixin` | 微信公众号文章 | mp.weixin.qq.com/s/* |
| `douyin-image` | 抖音图集 | douyin.com 分享链接 |
| `douyin-video` | 抖音视频 | douyin.com 分享链接 |
| `kuaishou-image` | 快手图集 | kuaishou.com 分享链接 |
| `kuaishou-video` | 快手视频 | kuaishou.com 分享链接 |
| `xiaohongshu-image` | 小红书图集 | xiaohongshu.com / xhslink.com |
| `xiaohongshu-video` | 小红书视频 | xiaohongshu.com / xhslink.com |
| `doubao` | 豆包 AI 生图分享页 | doubao.com/thread/* |
| `qianwen` | 千问 AI 生图分享页 | qianwen.com/share/* |

> 后端会按 URL 自动路由到对应处理器；`type` 同时作为落库记录类型。APP 抓取的图集 / 视频由同一链接自动识别内容类型。

### 成功响应

```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "all_url": ["https://...", "https://..."],
    "list": [
      {
        "id": 12345,
        "type": "webpic.douyin",
        "url": "https://v.douyin.com/xxxx",
        "content_type": "image",
        "list": ["https://...", "https://..."],
        "media": {
          "platform": "douyin",
          "title": "标题",
          "cover": "https://...",
          "author": "作者",
          "images": ["https://..."],
          "videos": [{ "url": "https://...", "quality": "1080p", "format": "mp4" }]
        }
      }
    ],
    "errors": [],
    "usage_count": 12
  }
}
```

字段说明：

- `all_url`：全部资源地址（去重合并）。
- `list[]`：按来源页分组；`id` 为 webpic 记录 ID，`type` 形如 `webpic.<subtype>`，可作为任务中心打包的 `job`。
- `content_type`：`image` 或 `video`。
- `list[].list`：该组资源地址数组。
- `media`：APP 抓取的元信息（标题、封面、作者、视频线路等）。
- `errors`：逐条失败原因（如链接与 type 不匹配）。
- `usage_count`：当前用户在对应产品线的已用次数。

### 失败 / 部分失败

- 整体失败：`code !== 1`，`msg` 为错误信息；图片类接口在部分失败时仍返回 `code=1`，逐条错误放入 `data.errors`。
- 鉴权失败：`code=10001`（需登录）/ `10002`（登录过期）。

## 4. 任务中心（打包下载）

抓取结果可通过 `list[].type`（如 `webpic.douyin`）+ `list[].id` 提交打包任务。

### 提交打包 POST /api/v2/job-center/submit

```json
{ "job": "webpic.douyin", "params": { "id": 12345 } }
```

也可用通用图片打包：`job = "zip"`，`params = { urls: ["https://..."] }`。

### 查询任务 POST /api/v2/job-center/list

```json
{ "page": 1, "per_page": 10 }
```

返回任务列表，含 `status`、`file_url`（完成后的下载地址）、`success_count`、`fail_count`。

## 5. 完整示例

### cURL

```bash
curl -X POST https://url2pic.php127.com/api/v3/go \
  -H 'Content-Type: application/json' \
  -H 'Key: u2p5f582fxxxxxxxxxc49a50dbda' \
  -H 'Sign: 3a8ee6a1b2' \
  -d '{"type":"douyin-image","urls":"https://v.douyin.com/xxxx"}'
```

### Node.js

```js
const body = JSON.stringify({ type: 'qianwen', urls: 'https://www.qianwen.com/share/chat/xxxx' });
const sign = require('crypto').createHash('md5').update(body).digest('hex').slice(0, 10);
const res = await fetch('https://url2pic.php127.com/api/v3/go', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Key: 'YOUR_API_KEY', Sign: sign },
  body,
});
const json = await res.json();
const images = json.data.list.flatMap((g) => g.list);
```

## 6. 注意事项

- 链接需与 `type` 匹配，否则该条记入 `errors`（如 `mp-weixin` 仅接受 `mp.weixin.qq.com/s` 文章页）。
- 单次最多 10 个链接。
- 图片地址可能经图片代理重写（带签名 HMAC），下载时直接使用返回地址即可。
- 豆包 / 千问抓取返回的是无水印原图。