yande.re Y站API翻译

网站链接：https://yande.re/help/api

Help: API 1.13.0+update.3

Moebooru提供的API和Danbooru API (version 1.13.0)大部分兼容，能够让您更方便的写脚本语言。
你需要的是一种GET和POST到URLs的方法。如果您能解析XML或者JSON的响应，这样更好，但不是很重要，简单的API意味着你可以用JavaScript, Perl, Python, Ruby甚至像bash或tcsh这样的shell语言编写脚本。

基础（Basics）

HTTP定义了两个请求方法：GET和POST。你将使用这两个方法与Danbooru API进行交互。大部分改变数据库状态的API调用（例如创建，更新，或者删除某些内容）需要进行HTTP POST调用。只检索数据的API调用通常可以使用HTTP GET调用来完成。
在Danbooru API中，URL和函数名类似。您将函数参数作为查询字符串传递，这里是一个非常简单的栗子：/post.xml?limit=1.

post部分表示我们正在使用的控制器。在这个栗子下是posts.index描述了动作。这里我们正在检索帖子列表。最后，xml部分描述了我们想要的响应格式。您可以写.xml指定为XML响应，.json指定为JSON响应，或者什么都不写指定为HTML响应。
.xml效果：

.json效果：

html效果：

响应

所有改变状态的API调用将返回单个元素响应（以XML调用为例）他们的格式如下：

<?xml version="1.0" encoding="UTF-8"?><response success="false" reason="duplicate"/>

对于JSON响应，他们将如下所示：

{success: false, reason: "duplicate"}

您通常可以根据响应对象来决定（调用）成功或者失败，您还可以根据HTTP状态码知道发生了什么。在标准状态码之外，Danbooru还使用一些范围在4xx到5xx的自定义状态码。

状态码 含义 200 OK 请求成功（Request was successful） 403 Forbidden 拒绝访问（Access denied） 404 Not Found 没有找到（Not found） 420 Invalid Record 记录无法保存（Record could not be saved） 421 User Throttled 用户被调节，稍后再试（User is throttled, try again later） 422 Locked 资源被锁定，无法修改（The resource is locked and cannot be modified） 423 Already Exists 资源已经存在（Resource already exists） 424 Invalid Parameters 给定的参数无效（The given parameters were invalid） 500 Internal Server Error 服务器上发生一些未知错误（Some unknown error occurred on the server） 503 Service Unavailable 服务器目前无法处理请求，稍后再试（Server cannot currently handle the request, try again later）

JSON响应

在大多数情况下，您可能希望使用XML，如果您在JavaScript中编写某些内容，那么JSON响应可能更好。JSON响应能够更快的被解析并且写更少的代码就可以获得你的数据结构。栗子：

var data = eval("(" + responseText + ")")alert(data.response)

登录

有些操作可能要求您登录。对于任何操作，您随时可以指定两个参数来标识自己：
login 您的登录名
password_hash 您的SHA1散列密码。简单的哈希您的纯密码将不会有效因为Danbooru给它的密码加Salt了（更难被破解）。实际上被哈希的字符串是”choujin-steiner–your-password–”。
请注意通过未加密的频道发送您的密码所涉及的安全风险。虽然您的密码将被散列，但是理论上仍然有可能根据您的散列密码创建一个假的cookie来窃取您的账户。

帖子（Posts）

获得列表（List）

基本的URL是 /post.xml.
limit 你想要检索的帖子的数量。每个请求都有最多100个帖子的限制。
page 页数。
tags 搜索的tags。在网站上工作的任何标签组合都可以在这里工作。这包括了所有的元标记。

创建（Create）

基本的URL是 /post/create.xml.
只有两个必填的字段：您需要提供标签（tags），您需要通过多部分表单或源URL提供文件。
post[tags] 空格分隔的标签列表
post[file] 以多部分形式编码的文件数据
post[rating] 此post的评级，可以是：安全的（safe），可疑的（questionable），成人向（18+）（explicit）
post[source] 如果这是URL，Danbooru会下载此文件
post[is_rating_locked] 设置为true以防止其他人改变评级
post[is_note_locked] 设置为true以防止请他人添加注释
post[parent_id] 父post的ID
md5 如果您希望Danbooru在上传后验证该文件，请提供MD5，如果MD5不匹配，此post被销毁。

如果调用失败，可能有以下响应原因：
MD5不匹配（MD5 mismatch）这意味着你提供了一个Danbooru 无法匹配的MD5参数，尝试再次上传此文件。
重复（duplicate）这个提交请求（post）已经存在于Danbooru（基于MD5哈希）中。将设置一个名为location的附加属性，指向原提交请求的（相对）URL。
其他（other）任何其他的错误将打印出其错误消息。
如果提交请求（post）上传成功，你将会在响应中得到一个名为location属性，指向你最近上传的帖子的（相对）URL。

更新（Update）

基本URL是 /post/update.xml. 只需要id参数。如果你不想改变其他参数，则将它们留空。
id 提交请求将要更新的id
post[tags] 空格分隔的标签列表
post[file] 以多部分形式编码的文件数据
post[rating] 此post的评级，可以是：安全的（safe），可疑的（18+）（questionable），明确的（explicit）
post[source] 如果这是URL，Danbooru会下载此文件
post[is_rating_locked] 设置为true以防止其他人改变评级
post[is_note_locked] 设置为true以防止请他人添加注释
post[parent_id] 父post的ID

删除（Destroy）

您必须登录才能使用这个操作。同时，您必须是上传此帖子的用户（或者您是主持人moderator）。
id 要删除的帖子的id号.

恢复标签（Revert Tags）

此操作恢复一个帖子到之前的标签集，基本的URL是 /post/revert_tags.xml.
id 要更新的帖子的id号。
history_id 历史标签的id号。

投票（Vote）

这个操作让你给一个帖子投票。你以一个IP地址只能给一个帖子投一票。基本URL是/post/vote.xml.
id 要更新的帖子的id号。
score 设置为1来赞同，设置为-1以否定。所有其他值会被忽略。
如果调用不成功，可能因为下面的原因：
already voted 你已经给这个帖子投过票了。
invalid score 你提供了一个无效的分数。

标签（Tags）

获得列表（List）

基本URL是 /tag.xml.
limit 检索的tags的数量。将它设置为0会返回所有tag。
page 页数
order 排列顺序，可以是date, count, 或者 name
id tag的id
after_id 返回所有id比此id更大的tags
name tag的准确名字
name_pattern 搜索任何名字中包含此参数的tag
一个栗子：

更新（Update）

name 要更新的标签的名称
tag[tag_type] tag类型。一般：0，艺术家：1，版权：3，角色：4
tag[is_ambiguous] 这个tag是否不明确，使用1表示不明确，使用0表示明确。

相关（Related）

基本URL是 /tag/related.xml.
tags 询问的tags名称
type 将结果限制在此tag类型，可以为general, artist, copyright,或者 character

艺术家（Artists）

获得列表（List）

基本URL是/artist.xml.
name 艺术家的名字（或名字的片段）
order 排列顺序，可以是date或者name
page 获取的页数
一个栗子：

创建（Create）

基本URL是 /artist/create.xml.
artist[name] 艺术家的名字
artist[urls] 与此艺术家相关的URLs列表，空格分隔。
artist[alias] 将创建艺术家是此字段代表艺术家的别名。只需输入别名。
artist[group] 此艺术家参与的组或圈子。只需输入该组的名称。

更新（Update）

基本URL是 /artist/update.xml. 只需要id参数，其他参数是可选的。
id 要更新的艺术家的id
artist[name] 艺术家的名字
artist[urls] 与此艺术家相关的URLs列表，空格分隔。
artist[alias] 将创建艺术家是此字段代表艺术家的别名。只需输入别名。
artist[group] 此艺术家参与的组或圈子。只需输入该组的名称。

删除（Destroy）

基本URL是 /artist/destroy.xml. 你必须登录才能删除艺术家。
id 将要删除的艺术家的id

评论（Comments）

展示评论（Show）

基本URL是 /comment/show.xml. 这将检索单个评论。
id 将要检索的评论的id

创建（Create）

基本URL是/comment/create.xml.
comment[anonymous] 如果你想匿名发表此评论，设置为1.
comment[post_id] 你此评论发表对象的id
comment[body] 评论的正文

删除（Destroy）

基本URL是 /comment/destroy.xml. 你必须登录才能使用此操作。同时你必须是此评论的发表者或者是主持人。
id 将要删除的评论的id

Wiki

所有标题必须是准确的（但是样例（case）和空格无关紧要）

获得列表（List）

基本的URL是 /wiki.xml. 这将检索所有wiki页面构成的列表。
order 你想要的页面的排列顺序。可以是：title，date
limit 要检索的总页数
page 检索特定页面的页码
query 将要搜索的一个单词或者词组
一个栗子：

创建（Create）

基本URL是 /wiki/create.xml.
wiki_page[title] 创建的wiki页面的标题
wiki_page[body] 创建的wiki页面的正文

更新（Update）

基本URL是 /wiki/update.xml. 可能的报错原因：“页面被锁定”
title 将要更新的wiki页面的原始标题
wiki_page[title] 此wiki页面的新标题
wiki_page[body] 此wiki页面的新正文

展示（Show）

基本URL是 /wiki/show.xml. 可能的报错原因：“艺术家类型”
title 将检索的wiki页面的标题
version 将检索的wiki页面的版本

删除（Destroy）

基本URL是 /wiki/destroy.xml. 你必须以创建人（moderator）身份登录才能使用此操作。
title 将删除的页面的标题

锁定（Lock）

基本URL是 /wiki/lock.xml. 你必须以创建人（moderator）身份登录才能使用此操作。
title 将锁定的页面的标题

解锁（Unlock）

基本URL是 /wiki/unlock.xml. 你必须以创建人（moderator）身份登录才能使用此操作。
title 将解锁的页面的标题

还原（Revert）

基本URL是 /wiki/revert.xml. 可能报错的原因：“页面被锁定”
title 将要更新的wiki页面的标题
version 将此页面恢复到的版本

历史（History）

基本URL是 /wiki/history.xml.
title 将要被检索历史版本的wiki页面的title

备注（Notes）

获得列表（List）

基本URL是 /note.xml.
post_id 将要检索的备注的post id
一个栗子：

搜索（Search）

基本URL是 /note/search.xml.
query 将要搜索的一个单词或词组

历史（History）

基本URL是 /note/history.xml. 你可以指定id，post_id或者什么都不指定。什么都不指定会给你一个包含所有备注当前版本信息的列表
limit 检索历史版本的数量
page 页面偏移量
post_id 将要被检索版本的备注的post id
id 将要被检索版本的备注的id

恢复（Revert）

基本URL是 /note/revert.xml. 可能的报错原因：“帖子被锁定”
id 将要被更新的备注的id
version 此备注将要恢复到的版本

创建/更新（Create/Update）

基本URL是 /note/update.xml. 备注和其他的控制器的不同点在于创建和更新的接口是相同的。如果你提供id参数，那么Danbooru会假定你正在更新一个现有的备注。否则，它会创建一个新的备注。可能的错误原因：“帖子被锁定”
id 如果你更新一个备注，这是被更新备注的id
note[post_id] 此备注属于的帖子的id
note[x] 此备注的x坐标
note[y] 此备注的y坐标
note[width] 此备注的宽度
note[height] 此备注的高度
note[is_active] 此备注是否可见，设置成1为可见，0为不可见
note[body] 此备注的信息

用户（Users）

搜索（Search）

基本URL是 /user.xml. 如果你不指定任何参数，你会得到一个包含所有用户的列表
id 用户的id
name 用户的名称
一个栗子：

论坛（Forum）

获得列表（List）

基本URL是 /forum.xml. 如果你不指定任何参数，你会得到一个包含所有父级主题的列表
parent_id 父级主题id，你将会得到该论坛帖子的所有回复
一个栗子：

同主题图片集合（Pools）

列表池（List Pools）

基本URL是 /pool.xml. 如果你不指定任何参数，你会得到一个包含所有同主题图片集合的列表
query 标题
page 页面
一个栗子：

帖子列表（List Posts）

基本URL是 /pool/show.xml. 如果你不指定任何参数，你会得到一个包含所有同主题图片集合的列表
id 此图片集合的id
page 图片集合的页数

更新（Update）

基本URL是 /pool/update.xml.
id 此图片集合的id
pool[name] 此图片集合的名称
pool[is_public] 值为1或0，1代表这个图片集合是公开的，0表示非公开
pool[description] 此图片集合的描述

创建（Create）

基本URL是 /pool/create.xml.
pool[name] 此图片集合的名称
pool[is_public] 值为1或0，1代表这个图片集合是公开的，0表示非公开
pool[description] 此图片集合的描述

删除（Destroy）

基本URL是 /pool/destroy.xml.
id 将要删除的图片集合的id

增加帖子（Add Post）

基本URL是 /pool/add_post.xml. 可能的报错原因：“帖子已经存在”，“访问被拒绝”
pool_id 将要添加此帖子的图片集合的id
post_id 将要添加的帖子的id

删除帖子（Remove Post）

基本URL是 /pool/remove_post.xml. 可能的错误原因：“访问被拒绝”
pool_id 将要删除此帖的图片集合的id
post_id 将要被删除的帖子的id

喜爱此图片的用户（Favorites）

喜爱此图片的用户列表（List Users）

基本URL是 /favorite/list_users.json 此操作没有XML类型的API
id 此图片帖子的id
一个栗子：

更新日志（Change Log）

1.13.0+update.3

把 “/index” 从API的URLs移除

1.13.0+update.2

重新添加 “favorite/list_users” 的API

1.13.0+update.1

给同主题图片集合（Pools）添加文档

1.13.0

修改艺术家有关的接口以使用新的URL系统
JSON请求现在会以.json后缀结尾
重命名了一些错误原因信息
把 “comment/index” 从API中移除
把url和md5参数从艺术家搜索中移除（可以将URL或者MD5哈希当做名称参数传递）

1.8.1

去掉 post[is_flagged] 属性