Pixiv Crawler: Common API Reference

Introduction#

During Pixiv crawler development, I investigated multiple Pixiv API endpoints in depth. This document summarizes commonly used APIs, request formats, and response structures from practical implementation work.

I also built a serverless Pixiv crawler recently:

Pixiv爬虫/下载/代理，无需服务器即可一键部署！

Example project:

https://github.com/evepupil/serverless_pixiv_crawlergithub.com/evepupil/serverless_pixiv_crawler

Basic configuration#

Request headers#

All API calls require proper headers, especially Cookie and User-Agent:

1
interface PixivHeaders {
2
  'User-Agent': string;
3
  cookie: string;
4
  Referer: string;
5
  'Accept-Language': string;
6
}

Common response format#

Most Pixiv APIs follow this structure:

1
{
2
  "error": false,
3
  "body": {
4
    // payload
5
  }
6
}

Core API endpoints#

1. Get illustration details#

Endpoint: https://www.pixiv.net/ajax/illust/{pid}

Method: GET

Parameters:

pid: illustration ID (required)

Response structure:

1
interface PixivIllustInfo {
2
  body: {
3
    userId: string;          // author user ID
4
    title: string;           // illustration title
5
    userName: string;        // author username
6
    tags: {
7
      tags: Array<{
8
        tag: string;         // tag name
9
        translation?: {
10
          en: string;        // english translation
11
        };
12
      }>;
13
    };
14
    likeCount: number;       // likes
15
    bookmarkCount: number;   // bookmarks
16
    viewCount: number;       // views
17
    illusts?: Array<{ id: string }>; // related illustrations
18
    recommendUsers?: Array<{
19
      userId: string;
20
      illustIds: string[];
21
    }>;
22
  };
23
  error: boolean;
24
}

Example:

1
const response = await axios.get(
2
  `https://www.pixiv.net/ajax/illust/123456789`,
3
  { headers: pixivHeaders }
4
);
5
const illustInfo: PixivIllustInfo = response.data;

2. Get illustration pages (image URLs)#

Endpoint: https://www.pixiv.net/ajax/illust/{pid}/pages?lang=zh

Method: GET

Parameters:

pid: illustration ID (required)
lang: language (default zh)

Response structure:

1
interface PixivIllustPagesResponse {
2
  body: Array<{
3
    urls: {
4
      original: string;      // original image
5
      regular: string;       // regular size
6
      small: string;         // small size
7
      thumb_mini: string;    // thumbnail
8
    };
9
  }>;
10
  error: boolean;
11
}

Example:

1
const response = await axios.get(
2
  `https://www.pixiv.net/ajax/illust/123456789/pages?lang=zh`,
3
  { headers: pixivHeaders }
4
);
5
const pagesInfo: PixivIllustPagesResponse = response.data;

3. Get illustration recommendations#

Endpoint: https://www.pixiv.net/ajax/illust/{pid}/recommend/init?limit=30&lang=zh

Method: GET

Parameters:

pid: illustration ID (required)
limit: number of results (default 30)
lang: language (default zh)

Response structure:

1
interface PixivRecommendResponse {
2
  body: {
3
    illusts: Array<{ id: string }>; // recommended illustration IDs
4
  };
5
  error: boolean;
6
}

Example:

1
const response = await axios.get(
2
  `https://www.pixiv.net/ajax/illust/123456789/recommend/init?limit=30&lang=zh`,
3
  { headers: pixivHeaders }
4
);
5
const recommendInfo: PixivRecommendResponse = response.data;

4. Get user recommendations#

Endpoint: https://www.pixiv.net/ajax/user/{userId}/recommends?userNum=30&workNum=5&isR18=false&lang=zh

Method: GET

Parameters:

userId: user ID (required)
userNum: number of recommended users (default 30)
workNum: number of works per user (default 5)
isR18: include R18 content (default false)
lang: language (default zh)

Response structure:

1
interface PixivUserRecommendResponse {
2
  body: {
3
    recommendUsers: Array<{
4
      userId: string;        // recommended user ID
5
      illustIds: string[];   // this user's illustration IDs
6
    }>;
7
  };
8
  error: boolean;
9
}

Example:

1
const response = await axios.get(
2
  `https://www.pixiv.net/ajax/user/123456/recommends?userNum=30&workNum=5&isR18=false&lang=zh`,
3
  { headers: pixivHeaders }
4
);
5
const userRecommendInfo: PixivUserRecommendResponse = response.data;

Ranking endpoint#

Fetch ranking data#

Endpoint: https://www.pixiv.net/ranking.php?mode={mode}&content=illust

Method: GET

Parameters:

mode: ranking type
daily: daily ranking
weekly: weekly ranking
monthly: monthly ranking
content: fixed as illust

Note: this endpoint returns HTML, so you need regex parsing to extract IDs.

Parsing example:

1
// Regex for illustration IDs
2
const pidRegex = /<a\s+[^>]*href=["']\/artworks\/(\d+)["'][^>]*>/g;
3
const pids: string[] = [];
4
let match: RegExpExecArray | null;
5

6
while ((match = pidRegex.exec(html)) !== null) {
7
  pids.push(match[1]);
8
}

Homepage recommendations#

Fetch homepage recommendation content#

Endpoint: https://www.pixiv.net/

Method: GET

Notes: homepage recommendations are also parsed from HTML, usually by locating elements with the data-gtm-work-id attribute.

Parsing example:

1
// Regex for recommended illustration IDs
2
const pidRegex = /data-gtm-work-id=["'](\d+)["']/gi;
3
const pids: string[] = [];
4
let match: RegExpExecArray | null;
5

6
while ((match = pidRegex.exec(html)) !== null) {
7
  pids.push(match[1]);
8
}

Error handling#

Common error types#

404: illustration does not exist or was deleted
403: insufficient permission or login required
429: rate limit exceeded

Error handling example#

1
try {
2
  const response = await axios.get(apiUrl, { headers });
3
  return response.data;
4
} catch (error) {
5
  if (error.response?.status === 404) {
6
    console.log('Illustration not found');
7
    return { error: true, status: 404, message: 'Image not found' };
8
  }
9
  throw error;
10
}

Best practices#

1. Request rate control#

1
// Add random delay to reduce ban risk
2
const delay = Math.random() * 2000 + 1000; // random 1-3s
3
await new Promise(resolve => setTimeout(resolve, delay));

2. Header rotation#

1
// Rotate among multiple header sets
2
const headersList: PixivHeaders[] = [
3
  { /* headers set 1 */ },
4
  { /* headers set 2 */ },
5
  { /* headers set 3 */ }
6
];
7

8
let headerIndex = 0;
9
const currentHeaders = headersList[headerIndex % headersList.length];
10
headerIndex++;

3. Retry mechanism#

1
async function requestWithRetry(url: string, maxRetries: number = 3) {
2
  for (let i = 0; i < maxRetries; i++) {
3
    try {
4
      const response = await axios.get(url, { headers });
5
      return response.data;
6
    } catch (error) {
7
      if (i === maxRetries - 1) throw error;
8
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
9
    }
10
  }
11
}

Summary#

This article, based on a production crawler implementation, summarizes the most useful Pixiv endpoints:

Illustration info: details, page URLs, recommendations
User-related data: recommended users and author metadata
Ranking data: daily / weekly / monthly ranking pages
Homepage recommendation parsing

When using these APIs:

Follow website terms of use
Control request frequency to avoid excessive load
Handle errors properly
Use proper headers and authentication context

Hope this reference helps developers working with Pixiv data.

Note: for learning and research only. Please follow applicable laws and platform terms.