{
  "openapi": "3.1.0",
  "info": {
    "title": "Pixiv 公开周榜 · 上游调用学习参考",
    "version": "1.0.0",
    "description": "学习用上游接口参考，按项目实际调用整理；非官方稳定契约。本项目当前由青龙调用脚本，未开放独立 HTTP 网关。示例为脱敏演示，文档页不会执行请求。"
  },
  "servers": [
    {
      "url": "https://www.pixiv.net"
    }
  ],
  "security": [],
  "externalDocs": {
    "url": "https://bismih-weekly-docs.pages.dev/pixiv/"
  },
  "paths": {
    "/ranking.php": {
      "get": {
        "operationId": "readWeeklyRanking",
        "summary": "读取公开插画周榜第一页",
        "description": "上游平台调用参考；没有浏览器在线调试功能。字段未覆盖整个平台协议。",
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "required": true,
            "description": "",
            "schema": {
              "type": "string"
            },
            "example": "weekly"
          },
          {
            "name": "content",
            "in": "query",
            "required": true,
            "description": "",
            "schema": {
              "type": "string"
            },
            "example": "illust"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "description": "",
            "schema": {
              "type": "string"
            },
            "example": "json"
          },
          {
            "name": "p",
            "in": "query",
            "required": true,
            "description": "",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "上游响应，必须同时核对 HTTP 与业务状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "date",
                    "contents"
                  ],
                  "properties": {
                    "date": {
                      "oneOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "integer"
                        }
                      ]
                    },
                    "date_range_text": {
                      "type": "string",
                      "description": ""
                    },
                    "contents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "illust_id": {
                            "type": "integer"
                          },
                          "rank": {
                            "type": "integer"
                          },
                          "title": {
                            "type": "string",
                            "description": ""
                          },
                          "user_name": {
                            "type": "string",
                            "description": ""
                          },
                          "user_id": {
                            "oneOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "integer"
                              }
                            ]
                          },
                          "url": {
                            "type": "string",
                            "description": ""
                          },
                          "is_masked": {
                            "type": "boolean"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "description": ""
                            }
                          },
                          "illust_content_type": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "date": "20261024",
                  "contents": [
                    {
                      "illust_id": 123456789,
                      "rank": 1,
                      "title": "示例作品",
                      "user_name": "示例作者",
                      "user_id": "42",
                      "url": "https://i.pximg.net/example-preview.jpg",
                      "is_masked": false,
                      "tags": [
                        "original"
                      ],
                      "illust_content_type": {
                        "sexual": 0,
                        "grotesque": 0,
                        "violent": 0
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "平台拒绝访问或要求验证；停止并检查会话"
          },
          "429": {
            "description": "平台限流；停止，不自动重发写请求"
          }
        }
      }
    },
    "/ajax/illust/{illust_id}/pages": {
      "get": {
        "operationId": "readIllustrationPages",
        "summary": "查询作品图片，仅使用首图",
        "description": "上游平台调用参考；没有浏览器在线调试功能。字段未覆盖整个平台协议。",
        "parameters": [
          {
            "name": "illust_id",
            "in": "path",
            "required": true,
            "description": "来自榜单的数字作品编号",
            "schema": {
              "type": "string"
            },
            "example": "123456789"
          }
        ],
        "responses": {
          "200": {
            "description": "上游响应，必须同时核对 HTTP 与业务状态",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "boolean"
                    },
                    "body": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "error": false,
                  "body": [
                    {
                      "urls": {
                        "original": "https://i.pximg.net/example-original.jpg"
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "平台拒绝访问或要求验证；停止并检查会话"
          },
          "429": {
            "description": "平台限流；停止，不自动重发写请求"
          }
        }
      }
    }
  },
  "x-implementation": "https://github.com/lizi-learn/bismih-weekly-publisher",
  "x-verified-baseline": "2026-10-26",
  "x-project-http-gateway": false
}