moth docs
Guides Images, video and music

Images, video and music

Media runs as a job, which you start with one request, read until it succeeds and then download.

  1. Start the job

    Send a job with a media model and a prompt. It answers 202 with the job already running and its hold taken.

  2. Read its status

    Read the job every few seconds until status is succeeded or failed, while progress runs from 0 to 1.

  3. Download the files

    Each output has a url on the API. Fetch it with the same key within 24 hours, since the job is forgotten after that.

  1. Start202POST /jobs answers at once, with the job running and its hold taken
  2. RunningRead GET /jobs/{id} every few seconds while progress goes from 0 to 1
  3. SucceededDownload the files within 24 hours. Images are charged per image, a clip or a song in full
    or
    FailedOr unfinished after an hour. Nothing is charged and the hold comes back
A job's hold is taken when it starts and settled when it ends, and its files can be fetched for 24 hours.
python
import os, time, requests

api = "https://api.runmoth.si/v1"
auth = {"Authorization": f"Bearer {os.environ['MOTH_API_KEY']}"}

job = requests.post(f"{api}/jobs", headers=auth, json={
    "model": "nano-banana-2", "prompt": "A moth resting on a warm lamp at night", "n": 2,
}).json()
while job["status"] in ("queued", "running"):
    time.sleep(3)
    job = requests.get(f"{api}/jobs/{job['id']}", headers=auth).json()

for out in job["outputs"]:
    image = requests.get(f"https://api.runmoth.si{out['url']}", headers=auth).content

Settings by kind

KindSettingsCharged per
Imagen up to the model's max_images, and aspect_ratio or sizeimage delivered
Videoduration_seconds from the model's durations, and aspect_ratiosecond, in full when it succeeds
Musicstyle and instrumentalsong

Each model's limits in the catalog lists what it takes. A setting outside them is refused with 400 before anything is held, and seed is refused on every model.

A failed job costs nothing. A job that fails, or hasn't finished after an hour, ends as failed and gives its whole hold back.

/images is the same endpoint limited to image models. It is not OpenAI's images API, and it answers with a job in the same way.