Using the API

= 1. Introduction = The API is the backbone of the website, and the way it interacts with the AIs, or store your content. As such, it can be used to use NovelAI in ways that were not necessarily thought or intended by the devs. Due to this, using the API comes with some restrictions that should be followed (ToS - sections 5.3 and 9.1) :
 * No account sharing. Any request using your access token should be done by you, and you only.
 * No automation. There is some leeway, but the basis of it is that there should be some form of user interaction, not letting a script run by itself for too long.

Failure to do so can result in your account's termination or your right to free generations being suspended (image.png - TODO: should probably host the image).

= 2. The endpoints = The official API docs can be viewed at docs, but might be vague on some points. Here is a breakdown of each endpoint, but without the documented arguments, types, and schemas, that are present in the docs. Each endpoint should be prepended with `https://api.novelai.net`.

Several responses can come from any endpoint:
 * A Cloudflare error with an HTML response
 * A normal error with a JSON response containing an "error" field for more information
 * The expected response

TODO: expain some concepts beforehand (access key, access token, encryption key, keystore, encryption of objects)

FIXME: long section, might benefit from collapsing. Extract long details out and explain them separately ?

2.1.1. /
Checks if the API is reachable

2.2.1. /user/register
Register an account. Automation is mitigated by ReCaptcha.

2.2.2. /user/login
Get a new access token from your access key. An access token is valid for 30 days from the moment of creation. More info on access key here.

2.2.3. /user/change-access-key
Change your access key and email (access key is based on email and password).

2.2.4. /user/resend-email-verification
Send an email with a verification token to verify your email address.

2.2.5. /user/verify-email
Verify your email address with the verification token sent to it.

2.2.6. /user/information
Get misc information about your account.

2.2.7. /user/deletion/request
Send an email to the account deletion. The email address should be the same you provided for the registration.

2.2.8. /user/deletion/delete
Confirm the account deletion with the deletion token to your email.

2.2.9. /user/recovery/request
Send an email to recover your account, in case you forgot your password. The email address should be the same you provided for the registration.

2.2.10. /user/recovery/recover
Change your access key, using the recovery token sent to your email.

2.2.11. /user/delete
Delete the account.

2.2.12. /user/data
Combination of all user data (/user/priority, /user/subscription, /user/keystore, /user/clientsettings, and /user/information)

2.2.13. /user/priority
Get the priority you have (legacy system, useless now)

2.2.14. /user/giftkeys
Get the gift keys you bought

2.2.15. /user/subscription
Get information about subscription, payment processor info, and current Anlas count

2.2.16. /user/keystore
Get/Edit the keystore. The keystore is a mapping meta -> encryption nonce as base64 string for each encrypted object (any object contain a "meta" field). The keystore doesn't exist (null) when it is empty, but creating a new story on the website will initialize it. The keystore is AES256 encrypted with your encryption key, which is different from the access key (more info here).

2.2.17. /user/objects/{type} (type = "stories", "storycontent", "aimodules", "shelf", "presets")
Get/Upload all the objects of a specific type, that you have uploaded to your account. "stories", "storycontent", and "aimodules" are encrypted, while "shelf" and "presets" are compressed using DEFLATE.

2.2.18. /user/objects/{type}/{id}
Get/Edit/Delete a specific object, that you have uploaded to your account.

2.2.19. /user/clientsettings
Get/Edit user-specific settings for the website, like font, theme, etc.

2.2.20. /user/submission
Submit content for an event hosted by NovelAI.

2.2.21. /user/submission/{event}
Get the content your submitted for the event.

2.2.22. /user/vote-submission/{event}
Vote, get your voting status, or delete your vote for an event.

2.3.1. /user/subscription/bind
Bind new subscription info from the payment processor to your account.

2.3.2. /user/subscription/change
Change the subscription tier to a new tier.

2.4. /ai/
Image generation requests expect all images to be sent as base64-encoded strings of PGN images, and return image(s) packed into a zip file using DEFLATE.

2.4.1. /ai/generate
Generate using one of the text AIs. For the input and output, see parameters.use_string.

For parameters.order, the the sampling methods are ordered, the disabled ones are removed, and they are then arranged into an array with temperature => 0, top_k => 1, top_p => 2, tfs => 3, top_a => 4, typical_p => 5

If parameters.num_logprobs is provided, a "logprobs" field will be added to the response, with the "chosen" token and the "before" token(s), for each token sent. Each logprob field has the token, the log probability before sampling, and the log probability after sampling.

TODO: expand on the arguments further ? Explain them ? Might take a lot of space depending on how thorough we get.

TODO: explain how the context need to be handled for models "hypebot" and "infillmodel".

2.4.2. /ai/generate-prompt
Unknown, no use yet.

2.4.3. /ai/generate-stream
Same as /ai/generate, but uses SSE to transmit the response one token at a time.

2.4.4. /ai/annotate-image
Get the mask for ControlNet, from an image. The parameters should contain a "image" field with the image to convert.

2.4.5. /ai/generate-image
Generate an image.

TODO: find a way to document the parameters cleanly, as there are 20 or so (see here). They are not documented in the docs.

2.4.6. /ai/upscale
Upscale the provided image.

2.4.7. /ai/classify
Unknown, no use yet.

2.4.8. /ai/generate-image/suggest-tags
Suggest tags with a certain confidence, considering how much the tag is used in the dataset. The confidence is between 0 and 1.

2.4.9. /ai/generate-voice
Generate an audio file reading the text sent. The endpoint accepts up to 1000 characters, any more being cut out. Even though this endpoint accepts arguments, they should be sent as URL arguments.

Voice is only relevant for TTS v1 (FIXME: verify this).

If "opus" is true, the audio file will be in WebM format, otherwise it will be MP3.

Version should be "v1" or "v2", depending on the TTS version you want to use.

2.5.1. /ai/module/train
Send a new module to the training queue. "lr" is the learning rate.

2.5.2. /ai/module/all
Get the modules currently in training or that finished training.

2.5.3. /ai/module/{id}
Get/Delete a module currently in training or that finished training.

2.5.4. /ai/module/buy-training-steps
Buy Anlas (steps) using your payment processor information.

3. Unofficial API resources:

 * C# - https://github.com/Draco18s/NovelAPI
 * Golang - https://github.com/wbrown/novelai-research-tool (more of a tool than an API, but uses the API)
 * Python - https://github.com/Aedial/novelai-api