necos

package module
v0.0.0-...-8be9d70 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2024 License: MIT Imports: 11 Imported by: 0

README

go-necos

Simple Nekos API wrapper written in Go

Go tests

Documentation for the API can be found by the links below:

nekosapi.com/docs | api.nekosapi.com/v3/docs

Usage

The wrapper provides you with a Client structure that has DefaultQuery field for setting the default query, which will be merged with every request from that Client, and Domain for setting base domain for all API calls.

All methods to interact with API (except 'Get a random image file redirect', which is not implemented) have the same names as in the documentation (with adding Get or Post prefixes here and there).

Mandatory arguments for calls are in the signature of methods and optional arguments are given through Request structure (simply a url.Values alias). What fields can be used by a call is stated in API docs or in the method comment.

To simplify the creation of Requests the wrapper gives you SetFields and AddFields functions that can set and add new fields to already existing Request or make a new one. Odd arguments are responsible for keys and even for values.

Also, since the API goal is to provide you with pictures, wrapper simplifies it here as well. You can use Save, SaveTemp and SaveSlice functions to create writers to file by given path, file in temp directory or to slice respectfully. The latter writers can be used by methods like DownloadImage, DownloadSample and Download to download images into them.

Examples of usage can be found in tests and in examples

Documentation

Index

Constants

View Source 
const (
	DefaultDomain   = "https://api.nekosapi.com/v3"
	Images          = "/images"
	RandomImages    = Images + "/random"
	ReportImage     = Images + "/report"
	Tags            = Images + "/tags"
	TagByID         = Tags + "/%d"
	TagImages       = TagByID + "/images"
	ImageByID       = Images + "/%d"
	ImageArtist     = ImageByID + "/artist"
	ImageCharacters = ImageByID + "/characters"
	ImageTags       = ImageByID + "/tags"

	Artists      = "/artists"
	ArtistByID   = Artists + "/%d"
	ArtistImages = ArtistByID + "/images"

	Characters      = "/characters"
	CharacterByID   = Characters + "/%d"
	CharacterImages = CharacterByID + "/images"
)

endpoint urls for wrapper to call

Variables

View Source 
var BadStatusError = errors.New("bad HTTP Status Code")

Functions

func Save 

func Save(name string) (io.WriteCloser, error)

Save writes file under given name

func SaveTemp 

func SaveTemp(pattern string) (io.WriteCloser, string, error)

SaveTemp writes file in a temporary directory and returns it's name

it's the callers responsibility to delete file after use

func SaveToSlice 

func SaveToSlice(dst *[]byte) io.WriteCloser

SaveToSlice return writer that saves it's content to RAM

Types

type Artist 

type Artist struct {
	ID           int
	IDv2         string `json:"id_v2"`
	Name         string
	Aliases      []string
	ImageURL     string `json:"image_url"`
	Links        []string
	PolicyRepost bool `json:"policy_repost"`
	PolicyCredit bool `json:"policy_credit"`
	PolicyAI     bool `json:"policy_ai"`
}

Artist is data type that represents artist data returned by API

returned by: /artists/{id}

type Character 

type Character struct {
	ID          int
	IDv2        string `json:"id_v2"`
	Name        string
	Aliases     []string
	Description string
	Ages        []int
	Height      int
	Weight      int
	Gender      string
	Species     string
	Birthday    string
	Nationality string
	Occupations []string
}

Character is data type that represents character data returned by API

returned by: /characters/{id}

type Client 

type Client struct {
	http.Client
	DefaultQuery url.Values
	Domain       string
}

Client is structure used to make calls to api easier

func NewClient 

func NewClient() *Client

func (*Client) CallAPI 

func (c *Client) CallAPI(method, path string, query url.Values, result interface{}) error

CallAPI is a plain api call, which uses context.Background()

func (*Client) CallAPIWithContext 

func (c *Client) CallAPIWithContext(ctx context.Context, method, path string, query url.Values, result interface{}) error

CallAPIWithContext is a plain api call

At first it builds query suffix from provided url.Values and DefaultQuery, makes request, and marshals response data

func (*Client) Download 

func (c *Client) Download(ctx context.Context, url string, dst io.WriteCloser) error

Download is the method used to download Images

Closes the file after finished reading

func (*Client) DownloadAppend 

func (c *Client) DownloadAppend(ctx context.Context, url string, dst io.Writer) error

DownloadAppend is the method used to do append downloaded to given writer

it makes a GET request to given url and writes received content to dst

func (*Client) DownloadImage 

func (c *Client) DownloadImage(im *Image, dst io.WriteCloser) error

DownloadImage downloads the Image with default context

closes the Writer

func (*Client) DownloadImageWithContext 

func (c *Client) DownloadImageWithContext(ctx context.Context, im *Image, dst io.WriteCloser) error

DownloadImageWithContext downloads the Image with given context

closes the Writer

func (*Client) DownloadSample 

func (c *Client) DownloadSample(im *Image, dst io.WriteCloser) error

DownloadSample downloads the sample of Image with default context

closes the Writer

func (*Client) DownloadSampleWithContext 

func (c *Client) DownloadSampleWithContext(ctx context.Context, im *Image, dst io.WriteCloser) error

DownloadSampleWithContext downloads the sample of Image with given context

closes the Writer

func (*Client) Get 

func (c *Client) Get(path string, query url.Values, result interface{}) error

Get is a wrapper for GET http method

func (*Client) GetArtistByID 

func (c *Client) GetArtistByID(id int) (Artist, error)

GetArtistByID is a wrapper for ArtistByID endpoint

func (*Client) GetArtistByIDWithContext 

func (c *Client) GetArtistByIDWithContext(ctx context.Context, id int) (Artist, error)

GetArtistByIDWithContext is a wrapper for ArtistByID endpoint

func (*Client) GetArtistImages 

func (c *Client) GetArtistImages(id int, req Request) (MultipleContainer[Image], error)

GetArtistImages is a wrapper for ArtistImages endpoint

Request for GetArtistImages supports those parameters:

  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetArtistImagesWithContext 

func (c *Client) GetArtistImagesWithContext(ctx context.Context, id int, req Request) (MultipleContainer[Image], error)

GetArtistImagesWithContext is a wrapper for ArtistImages endpoint

func (*Client) GetArtists 

func (c *Client) GetArtists(req Request) (MultipleContainer[Artist], error)

GetArtists is a wrapper for Artists endpoint

Request for GetArtists supports those parameters:

  • search (string) - Search term. Will return all tags with this term(s) in their name or description
  • policy_repost (boolean) - Does this artist allow you to repost their art in other places?
  • policy_credit (boolean) - Are you required to credit the artist when using their art?
  • policy_ai (boolean) - Does the artist allow you to use their art for AI projects (AI training)?
  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetArtistsWithContext 

func (c *Client) GetArtistsWithContext(ctx context.Context, req Request) (MultipleContainer[Artist], error)

GetArtistsWithContext is a wrapper for Artists endpoint

For more info on Request parameters see GetArtists

func (*Client) GetCharacterByID 

func (c *Client) GetCharacterByID(id int) (Character, error)

GetCharacterByID is a wrapper for CharacterByID endpoint

func (*Client) GetCharacterByIDWithContext 

func (c *Client) GetCharacterByIDWithContext(ctx context.Context, id int) (Character, error)

GetCharacterByIDWithContext is a wrapper for CharacterByID endpoint

func (*Client) GetCharacterImages 

func (c *Client) GetCharacterImages(id int, req Request) (MultipleContainer[Image], error)

GetCharacterImages is a wrapper for CharacterImages endpoint

Request for GetCharacterImages supports those parameters:

  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetCharacterImagesWithContext 

func (c *Client) GetCharacterImagesWithContext(ctx context.Context, id int, req Request) (MultipleContainer[Image], error)

GetCharacterImagesWithContext is a wrapper for CharacterImages endpoint

For more info on Request parameters see GetCharacterImages

func (*Client) GetCharacters 

func (c *Client) GetCharacters(req Request) (MultipleContainer[Character], error)

GetCharacters is a wrapper for Characters endpoint

Request for GetCharacters supports those parameters:

  • search (string) - probably searches for the term in name and description
  • age (array of integers) - One or more of the character's (official) ages.
  • gender (string)
  • species (string)
  • nationality (string)
  • occupation (array of strings) - Occupations the character officially has/has officially had.
  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetCharactersWithContext 

func (c *Client) GetCharactersWithContext(ctx context.Context, req Request) (MultipleContainer[Character], error)

GetCharactersWithContext is a wrapper for Characters endpoint

For more info on Request parameters see GetCharacters

func (*Client) GetImageArtist 

func (c *Client) GetImageArtist(id int) (Artist, error)

GetImageArtist is a wrapper for ImageArtist endpoint

func (*Client) GetImageArtistWithContext 

func (c *Client) GetImageArtistWithContext(ctx context.Context, id int) (Artist, error)

GetImageArtistWithContext is a wrapper for ImageArtist endpoint

func (*Client) GetImageByID 

func (c *Client) GetImageByID(id int) (Image, error)

GetImageByID is a wrapper for ImageByID endpoint

func (*Client) GetImageByIDWithContext 

func (c *Client) GetImageByIDWithContext(ctx context.Context, id int) (Image, error)

GetImageByIDWithContext is a wrapper for ImageByID endpoint

func (*Client) GetImageCharacters 

func (c *Client) GetImageCharacters(id int, req Request) (MultipleContainer[Character], error)

GetImageCharacters is a wrapper for ImageCharacters endpoint

Request for GetImageCharacters supports those parameters:

  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

This method isn't recommended to use since most of the time the server only returns 500 (internal server error)

func (*Client) GetImageCharactersWithContext 

func (c *Client) GetImageCharactersWithContext(ctx context.Context, id int, req Request) (MultipleContainer[Character], error)

GetImageCharactersWithContext is a wrapper for ImageCharacters endpoint

This method isn't recommended to use since most of the time the server only returns 500 (internal server error)

func (*Client) GetImageTags 

func (c *Client) GetImageTags(id int, req Request) (MultipleContainer[Tag], error)

GetImageTags is a wrapper for ImageTags endpoint

Request for GetImageTags supports those parameters:

  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

This method isn't recommended to use since most of the time the server only returns 500 (internal server error)

func (*Client) GetImageTagsWithContext 

func (c *Client) GetImageTagsWithContext(ctx context.Context, id int, req Request) (MultipleContainer[Tag], error)

GetImageTagsWithContext is a wrapper for ImageTags endpoint

This method isn't recommended to use since most of the time the server only returns 500 (internal server error)

func (*Client) GetImages 

func (c *Client) GetImages(req Request) (MultipleContainer[Image], error)

GetImages is a wrapper for Images endpoint

Request for GetImages supports those parameters:

  • rating (array of strings)
  • is_original (boolean)
  • is_screenshot (boolean)
  • is flagged (boolean) - whether the image is flagged by mods
  • is animated (boolean)
  • artist (integer) - the arist's ID
  • character (array of integers) - the character's ID
  • tag (array of integers) - the tag's ID
  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetImagesWithContext 

func (c *Client) GetImagesWithContext(ctx context.Context, req Request) (MultipleContainer[Image], error)

GetImagesWithContext is a wrapper for Images endpoint

For more info on Request parameters see GetImages

func (*Client) GetRandomImages 

func (c *Client) GetRandomImages(req Request) (MultipleContainer[Image], error)

GetRandomImages is a wrapper for RandomImages endpoint

Request for GetRandomImages supports those parameters:

  • rating (array of strings)
  • is_original (boolean)
  • is_screenshot (boolean)
  • is flagged (boolean) - whether the image is flagged by mods
  • is animated (boolean)
  • artist (integer) - the arist's ID
  • character (array of integers) - the character's ID
  • tag (array of integers) - the tag's ID
  • limit (integer) - [1..100], default = 100

func (*Client) GetRandomImagesWithContext 

func (c *Client) GetRandomImagesWithContext(ctx context.Context, req Request) (MultipleContainer[Image], error)

GetRandomImagesWithContext is a wrapper for RandomImages endpoint

For more info on Request parameters see GetRandomImages

func (*Client) GetTagByID 

func (c *Client) GetTagByID(id int) (Tag, error)

GetTagByID is a wrapper for TagByID endpoint

func (*Client) GetTagByIDWithContext 

func (c *Client) GetTagByIDWithContext(ctx context.Context, id int) (Tag, error)

GetTagByIDWithContext is a wrapper for TagByID endpoint

func (*Client) GetTagImages 

func (c *Client) GetTagImages(tagID int, req Request) (MultipleContainer[Image], error)

GetTagImages is a wrapper for TagImages endpoint

Request for GetTagImages supports those parameters:

  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetTagImagesWithContext 

func (c *Client) GetTagImagesWithContext(ctx context.Context, tagID int, req Request) (MultipleContainer[Image], error)

GetTagImagesWithContext is a wrapper for TagImages endpoint

func (*Client) GetTags 

func (c *Client) GetTags(req Request) (MultipleContainer[Tag], error)

GetTags is a wrapper for Tags endpoint

Request for GetTags supports those parameters:

  • search (string) - search for a tag by name or description
  • is_nsfw (boolean)
  • limit (integer) - [1..100], default = 100
  • offset (integer) - >= 0, default = 0

func (*Client) GetTagsWithContext 

func (c *Client) GetTagsWithContext(ctx context.Context, req Request) (MultipleContainer[Tag], error)

GetTagsWithContext is a wrapper for Tags endpoint

For more info on Request parameters see GetTags

func (*Client) GetWithContext 

func (c *Client) GetWithContext(ctx context.Context, path string, query url.Values, result interface{}) error

GetWithContext is a wrapper for GET http method

func (*Client) Post 

func (c *Client) Post(path string, query url.Values, result interface{}) error

Post is a wrapper for POST http method

func (*Client) PostReport 

func (c *Client) PostReport(req Report) error

PostReport is a wrapper for ReportImage endpoint

Report for PostReport supports those parameters:

  • id (integer) - probably the id of Image
  • url (string) - probably the url of Image

func (*Client) PostReportWithContext 

func (c *Client) PostReportWithContext(ctx context.Context, req Report) error

PostReportWithContext is a wrapper for ReportImage endpoint

For more info on Report parameters see PostReport

func (*Client) PostWithContext 

func (c *Client) PostWithContext(ctx context.Context, path string, query url.Values, result interface{}) error

PostWithContext is a wrapper for POST http method

type Color 

type Color [3]int

Color is custom data used in parsing of colors

type Image 

type Image struct {
	ID             int
	IDv2           string `json:"id_v2"`
	ImageURL       string `json:"image_url"`
	SampleURL      string `json:"sample_url"`
	ImageSize      int    `json:"image_size"`
	ImageWidth     int    `json:"image_width"`
	ImageHeight    int    `json:"image_height"`
	SampleSize     int    `json:"sample_size"`
	SampleWidth    int    `json:"sample_width"`
	SampleHeight   int    `json:"sample_height"`
	Source         string
	SourceID       int     `json:"source_id"`
	Rating         string  `json:"rating"`
	Verification   string  `json:"verification"`
	HashMD5        string  `json:"hash_md5"`
	HashPerceptual string  `json:"hash_perceptual"`
	ColorDominant  Color   `json:"color_dominant"`
	ColorPalette   []Color `json:"color_palette"`
	Duration       int     `json:"duration"`
	IsOriginal     bool    `json:"is_original"`
	IsScreenshot   bool    `json:"is_screenshot"`
	IsFlagged      bool    `json:"is_flagged"`
	IsAnimated     bool    `json:"is_animated"`
	Artist         Artist
	Characters     []Character
	Tags           []Tag
	CreatedAt      float64 `json:"created_at"`
	UpdatedAt      float64 `json:"updated_at"`
}

Image is struct representing the image data returned by API

returned by: /images/{id}

func (*Image) GetName 

func (im *Image) GetName() string

GetName returns Image name

func (*Image) GetPattern 

func (im *Image) GetPattern() string

GetPattern makes a pattern to use in SaveTemp

it assumes that ImageSample and Image have the same extension

func (*Image) GetSampleName 

func (im *Image) GetSampleName() string

GetSampleName returns ImageSample name

type MultipleContainer 

type MultipleContainer[T any] struct {
	Items []T
	Count int
}

MultipleContainer is struct that is returned when there can be more than one answer to the request

returned by: /images, /images/random, /images/tags, /images/tags/{id}/images, /images/{id}/characters, /images/{id}/tags, /artists, /artist/{id}/images, /characters, /characters/{id}/images

type Report 

type Report = url.Values

Report contains data needed to make POST request to report an image. Should contain id (integer) or url (string)

type Request 

type Request = url.Values

Request is data needed to make GET request to any of endpoints using URL query

since all fields are optional and nothing breaks in the API when providing extra fields I decided it would be easier to make it from url.Values and don't make extra struct (url.Values is also easy to encode to query syntax)

list of possible fields: search (string), id (integer), rating (array of strings), is_original (boolean), is_screenshot (boolean), is_flagged (boolean), is_animated (boolean), is_nsfw (boolean), policy_repost (boolean), policy_credit (boolean), policy_ai (boolean), artist (integer), character (array of integers), age (array of integers), gender (string), species (string), nationality (string), occupation (array of strings), tag (array of integers), limit (integer) [1...100, 100 by default], offset (integer) [>=0, 0 by default]

func AddFields 

func AddFields(r Request, args ...any) Request

AddFields adds given fields to Request, odd are considered keys and even values, args should be convertible to string

if given nil Request makes Request itself

panics on uneven number of args

func OneValue 

func OneValue() Request

func SafeRequest 

func SafeRequest() Request

func SetFields 

func SetFields(r Request, args ...any) Request

SetFields sets given fields to Request; odd are considered keys and even values args should be convertible to string

if given nil Request makes Request itself

panics on uneven number of args

type Tag 

type Tag struct {
	ID          int
	IDv2        string `json:"id_v2"`
	Name        string
	Description string
	Sub         string
	IsNSFW      bool `json:"is_nsfw"`
}

Tag is data type that represents tag data returned by API

returned by: /images/tags/{id}

Source Files

View all Source files

Directories

Path Synopsis
examples
1.download_image

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.