API reference

class gseai.QueueError(job)

Bases: Exception

Raised when a queued job finishes with status 'error' or 'cancelled'.

Parameters:: job (dict)

job: The full job record dict returned by the server.

class gseai.GSEAIServer(api_token, host='gseai.gse.buffalo.edu', port=11434, timeout=None)

Bases: object

Client for the GSE AI LocalAI server.

Parameters:

api_token (str) – Bearer token for authentication.
host (str) – Hostname of the server.
port (int) – Port the server listens on.
timeout (float | None) – Request timeout in seconds. None (default) means no timeout, which is recommended for slow models.

close()

Return type:: None

list_models()

GET /v1/models — list available models.

Return type:: dict

chat(model, prompt, *, system_prompt=None, temperature=None, max_tokens=None, stream=False)

Convenience wrapper for single-turn chat.

Parameters:

model (str) – Model identifier.
prompt (str) – User message as a plain string.
system_prompt (str | None) – Optional system message.
temperature (float | None) – Sampling temperature (0–2).
max_tokens (int | None) – Maximum tokens to generate.
stream (bool) – If True, return a generator of SSE event dicts.

Return type:

dict | Generator[dict, None, None]

Returns:

Response dict, or a generator of SSE event dicts when stream=True.

chat_completions(model, messages, *, temperature=None, max_tokens=None, stream=False, top_p=None, top_k=None, stop=None, presence_penalty=None, frequency_penalty=None, repeat_penalty=None, logit_bias=None, seed=None, response_format=None, tools=None, tool_choice=None)

POST /v1/chat/completions — OpenAI-compatible chat completions.

Parameters:

model (str) – Model identifier.
messages (list[dict]) – List of message dicts with role and content.
temperature (float | None) – Sampling temperature (0–2).
max_tokens (int | None) – Maximum tokens to generate.
stream (bool) – If True, return a generator of SSE event dicts.
top_p (float | None) – Nucleus sampling (0–1).
top_k (int | None) – Top-k sampling limit.
stop (str | list[str] | None) – Stop sequence(s).
presence_penalty (float | None) – Presence penalty (-2 to 2).
frequency_penalty (float | None) – Frequency penalty (-2 to 2).
repeat_penalty (float | None) – Repetition penalty.
logit_bias (dict | None) – Token probability bias adjustments.
seed (int | None) – Random seed for reproducibility.
response_format (dict | None) – JSON schema for structured output.
tools (list[dict] | None) – Function definitions for tool/function calling.
tool_choice (str | None) – Tool selection mode — “auto”, “none”, or “required”.

Return type:

dict | Generator[dict, None, None]

completions(model, prompt, *, max_tokens=None, temperature=None, top_p=None, top_k=None, stop=None, frequency_penalty=None, presence_penalty=None, stream=False, seed=None)

POST /v1/completions — legacy text completions.

Parameters:

model (str) – Model identifier.
prompt (str | list) – Input text or list of texts.
max_tokens (int | None) – Maximum tokens to generate.
temperature (float | None) – Sampling temperature (0–2).
top_p (float | None) – Nucleus sampling (0–1).
top_k (int | None) – Top-k sampling limit.
stop (str | list[str] | None) – Stop sequence(s).
frequency_penalty (float | None) – Frequency penalty (-2 to 2).
presence_penalty (float | None) – Presence penalty (-2 to 2).
stream (bool) – If True, return a generator of SSE event dicts.
seed (int | None) – Random seed.

Return type:

dict | Generator[dict, None, None]

embeddings(model, input, *, encoding_format=None, dimensions=None)

POST /v1/embeddings — generate text embeddings.

Parameters:

model (str) – Model identifier.
input (str | list[str]) – Text or list of texts to embed.
encoding_format (str | None) – Output format — “float” or “base64”.
dimensions (int | None) – Target embedding dimensionality.

Return type:

dict

responses(model, messages, **kwargs)

POST /v1/responses — stateful chat responses (OpenAI-compatible).

Parameters:

model (str) – Model identifier.
messages (list[dict]) – List of message dicts with role and content.
**kwargs (Any) – Additional parameters forwarded to the endpoint.

Return type:

dict

messages(model, messages, max_tokens, *, system=None, temperature=None, top_p=None, top_k=None)

POST /v1/messages — Anthropic-compatible messages API.

Parameters:

model (str) – Model identifier.
messages (list[dict]) – List of message dicts with role and content.
max_tokens (int) – Maximum tokens to generate (required by the API).
system (str | None) – System prompt.
temperature (float | None) – Sampling temperature.
top_p (float | None) – Nucleus sampling (0–1).
top_k (int | None) – Top-k sampling limit.

Return type:

dict

transcribe(model, file_path, *, language=None, prompt=None, response_format='json')

POST /v1/audio/transcriptions — transcribe audio to text.

Parameters:

model (str) – Whisper model identifier.
file_path (str) – Path to the audio file.
language (str | None) – Source language code (e.g. "en"); auto-detected if omitted.
prompt (str | None) – Optional context hint passed to the model.
response_format (str) – One of "json", "verbose_json", "text", "srt", or "vtt" (default "json").

Return type:

dict | str

Returns:

Parsed dict for JSON formats, plain text string otherwise.

translate(model, file_path, *, prompt=None, response_format='json')

POST /v1/audio/translations — transcribe audio and translate to English.

Parameters:

model (str) – Whisper model identifier.
file_path (str) – Path to the audio file.
prompt (str | None) – Optional context hint passed to the model.
response_format (str) – One of "json", "verbose_json", "text", "srt", or "vtt" (default "json").

Return type:

dict | str

Returns:

Parsed dict for JSON formats, plain text string otherwise.

speech(model, input, *, voice=None, speed=None)

POST /v1/audio/speech — synthesize speech from text.

Parameters:

model (str) – TTS model identifier.
input (str) – Text to synthesize.
voice (str | None) – Voice identifier.
speed (float | None) – Playback speed multiplier (default 1.0).

Return type:

bytes

Returns:

Raw audio bytes.

generate_image(model, prompt, *, n=None, size=None, steps=None, seed=None)

POST /v1/images/generations — generate images from a text prompt.

Parameters:

model (str) – Image generation model identifier.
prompt (str) – Text description of the desired image.
n (int | None) – Number of images to generate.
size (str | None) – Output dimensions, e.g. "512x512".
steps (int | None) – Diffusion steps.
seed (int | None) – Random seed for reproducibility.

Return type:

dict

edit_image(model, image_path, prompt, *, mask_path=None, n=None, size=None)

POST /v1/images/edits — edit an image guided by a text prompt.

Parameters:

model (str) – Image model identifier.
image_path (str) – Path to the source image.
prompt (str) – Edit instruction.
mask_path (str | None) – Optional greyscale mask (white = region to edit).
n (int | None) – Number of variants to generate.
size (str | None) – Output dimensions, e.g. "512x512".

Return type:

dict

image_variation(model, image_path, *, n=None, size=None)

POST /v1/images/variations — generate variations of an existing image.

Parameters:

model (str) – Image model identifier.
image_path (str) – Path to the source image.
n (int | None) – Number of variations to generate.
size (str | None) – Output dimensions, e.g. "512x512".

Return type:

dict

submit_job(job_name, model, prompt, *, job_type='chat', system_prompt=None, temperature=0.0, max_tokens=8192)

POST /queue/jobs — submit a text-in async inference job.

Covers job types that take a text prompt: "chat", "embeddings", "speech", and "image_generate". For file-in job types use submit_file_job() instead.

Returns immediately with {job_id, status}. The job runs in the server’s background worker and can be polled with get_job().

Parameters:

job_name (str) – Human-readable label shown in queue listings.
model (str) – Model identifier.
prompt (str) – User message / input text.
job_type (str) – One of "chat" (default), "embeddings", "speech", or "image_generate".
system_prompt (str | None) – Optional system message (chat only).
temperature (float) – Sampling temperature (chat only, default 0.0).
max_tokens (int) – Maximum tokens to generate (chat only, default 8192).

Return type:

dict

Returns:

Dict with job_id and status (always "pending").

submit_file_job(job_name, job_type, model, file_path, *, prompt='', response_format='text')

POST /queue/jobs/upload — submit a file-in async inference job.

Covers job types that take a file: "transcribe", "translate", "image_edit", and "image_variation". For text-in job types use submit_job() instead.

Parameters:

job_name (str) – Human-readable label shown in queue listings.
job_type (str) – One of "transcribe", "translate", "image_edit", or "image_variation".
model (str) – Model identifier.
file_path (str) – Path to the input audio or image file.
prompt (str) – Edit instruction (image_edit only; ignored otherwise).
response_format (str) – One of "text" (default), "json", "verbose_json", "srt", or "vtt". Only applies to "transcribe" and "translate"; ignored otherwise. Mirrors transcribe()’s response_format, but unlike the synchronous endpoint the result comes back as the result field of the job record (a string in all cases, since none of these formats are binary) rather than as a response body.

Return type:

dict

Returns:

Dict with job_id and status (always "pending").

get_job(job_id)

GET /queue/jobs/{job_id} — return the full job record.

Parameters:: job_id (str) – UUID returned by submit_job().
Return type:: dict
Returns:: Full job record dict including owner, status, result, error, tokens_generated, and timestamps.
Raises:: httpx.HTTPStatusError – 404 if the job does not exist; 403 if it belongs to a different user (server returns the same "Job not found" message for both to avoid leaking existence).

list_jobs(*, status=None, model=None, job_type=None, limit=200)

GET /queue/jobs — list the caller’s jobs with optional filtering.

Parameters:

status (str | None) – Filter by status ("pending", "running", "done", "error", "cancelled").
model (str | None) – Filter by model identifier.
job_type (str | None) – Filter by job type ("chat", "speech", etc.).
limit (int) – Maximum number of results (default 200).

Return type:

list[dict]

Returns:

List of job summary dicts (no result or prompt fields).

cancel_job(job_id)

DELETE /queue/jobs/{job_id} — cancel a pending job.

Only pending jobs can be cancelled.

Parameters:: job_id (str) – UUID of the job to cancel.
Return type:: dict
Returns:: Dict with job_id and status ("cancelled").
Raises:: httpx.HTTPStatusError – 403/404 if the job does not exist or belongs to a different user; 409 if the job is not in pending status.

cancel_all_jobs()

Cancel all pending jobs belonging to the caller.

Return type:: list[dict]
Returns:: List of cancellation response dicts (each with job_id and status), one per job that was cancelled. Returns an empty list if there are no pending jobs.

get_job_result(job_id)

GET /queue/jobs/{job_id}/result — download a binary result.

Used for job types whose output is a file: "speech" (audio/mpeg), "image_generate", "image_edit", and "image_variation" (image/png). For text-result job types the output is in the "result" field of get_job() instead.

Parameters:: job_id (str) – UUID returned by submit_job() or submit_file_job().
Return type:: bytes
Returns:: Raw bytes of the audio or image file.
Raises:: httpx.HTTPStatusError – 404 if the job does not exist or belongs to a different user; 409 if the job is not yet done; 404 if the job type does not produce a binary result.

wait_for_job(job_id, *, interval=60.0, timeout=None)

Poll a job until it finishes and return the full job record.

Parameters:

job_id (str) – UUID returned by submit_job().
interval (float) – Seconds between polls (default 60).
timeout (float | None) – Maximum seconds to wait before raising TimeoutError. None (default) means wait indefinitely.

Return type:

dict

Returns:

Full job record dict when status is "done".

Raises:

QueueError – If the job finishes with status "error" or "cancelled".
TimeoutError – If timeout is set and the job has not finished within that many seconds.