Mod images API

From Official Factorio Wiki
Jump to navigation Jump to search
Category: Public API

The mod images API is used to add, reorder or remove mod images on the Factorio mod portal. It requires an API key with the ModPortal: Edit Mods usage, which can be created on https://factorio.com/profile.

It accepts multipart/form-data HTTP requests and responds with JSON encoded objects.

Endpoints

add

URL https://mods.factorio.com/api/v2/mods/images/add
HTTP Method POST

HTTP Request Header

Authorization Bearer $APIKey Authorization header with the APIKey and a "Bearer " prefix -> "Bearer $APIKey"

HTTP Request Body

mod string Name of the mod, for which a new image will be uploaded

JSON object response

upload_url string URL the image should be uploaded to
error string This attribute only appears on failed requests.
message string This attribute only appears on failed requests. Has details about the problem.

finish_upload

URL $upload_url URL returned by the add endpoint
HTTP Method POST

HTTP Request Body

image Image file

JSON object response

id string This attribute only appears on successful uploads. SHA1 of the uploaded image.
url string This attribute only appears on successful uploads. Url of the uploaded image.
thumbnail string This attribute only appears on successful uploads. Url of thumbnail of the uploaded image.
error string This attribute only appears on failed uploads.
message string This attribute only appears on failed uploads. Has details about the problem.

edit

URL https://mods.factorio.com/api/v2/mods/images/edit
HTTP Method POST

HTTP Request Header

Authorization Bearer $APIKey Authorization header with the APIKey and a "Bearer " prefix -> "Bearer $APIKey"

HTTP Request Body

mod string Name of the mod, for which a new image will be uploaded
images string List of comma-seperated image ids that should be displayed on the mod page


JSON object response

success bool This attribute only appears on successful uploads. It's set to true.
images list This attribute only appears on successful uploads. List of objects with id, url and thumbnail attribute same as finish_upload endpoint.
error string This attribute only appears on failed uploads.
message string This attribute only appears on failed uploads. Has details about the problem.

Possible API Error Responses

Possible values for the error property of API responses

InvalidApiKey Missing or invalid API key for the current endpoint
InvalidRequest Invalid request.
InternalError Internal error, please try again later.
Forbidden Insufficent permission for current endpoint
Unknown Unknown error, please try again later.
InvalidImageUpload Invalid image file uploaded.
UnknownMod Mod does not exist in mod portal

Python Examples

Add Image

import sys
import requests
from os import getenv

MOD_PORTAL_URL = "https://mods.factorio.com"
INIT_UPLOAD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/images/add"

apikey = getenv("MOD_EDIT_API_KEY")
modname = sys.argv[1]
filepath = sys.argv[2]

request_body = data = {"mod": modname}
request_headers = {"Authorization": f"Bearer {apikey}"}

response = requests.post(INIT_UPLOAD_URL, data=request_body, headers=request_headers)

if not response.ok:
    print(f"init_upload failed: {response.text}")
    sys.exit(1)

upload_url = response.json()["upload_url"]

with open(filepath, "rb") as f:
    request_body = {"image": f}
    response = requests.post(upload_url, files=request_body)

if not response.ok:
    print(f"upload failed: {response.text}")
    sys.exit(1)

print(f"upload successful: {response.text}")

Edit Images

import sys
import requests
from os import getenv

MOD_PORTAL_URL = "https://mods.factorio.com"
EDIT_MOD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/images/edit"

apikey = getenv("MOD_EDIT_API_KEY")
modname = getenv("MOD_NAME")

image_ids = ["fdc375d5ca3c263fedafb7ef143c82f9fb668472", "47bda5cd27ef49fe86fe03f803cb5c351a848586"]
image_ids_text = ",".join(image_ids)

request_body = data = {"mod": modname, "images": image_ids_text}
request_headers = {"Authorization": f"Bearer {apikey}"}

response = requests.post(EDIT_MOD_URL, data=request_body, headers=request_headers)

if not response.ok:
    print(f"edit failed: {response.text}")
    sys.exit(1)

print(f"edit successful: {response.text}")