Request syntax reference
Every Client.model(id) request the SDK ships — chat, embeddings, speech, images, video, jobs, uploads and capabilities — named exactly as infimal.request.Request implements them. Nothing on this page is a proposal.
What ships today
Client.from_env().model(listing_id) returns a handle; a surface method — chat, embeddings, speech, images, video — builds one Request; modifiers set fields; run() or stream() submits it once. Every method below is named exactly as the SDK ships it in infimal.request.Request.
Stack, Service, app.<model_type> and per-call bid() terms are design proposals with no working code path to a deployment (docs/sdk.md, "Proposals, not built"); they do not appear on this page, or anywhere else on the site (D361). Calling bid() on a real Request raises NotImplementedError.
Requests available now
Install the current infimal SDK. Set INFIMAL_API_KEY and optionally INFIMAL_ENDPOINT; Client.from_env() reads them. Supply a listing id from GET /v1/models. These examples are synchronous Python.
Each request submits once. Chat run() returns text and usage; chat stream() yields text deltas. Embeddings return vectors in input order. Speech run() returns bytes; its stream() yields transport chunks, not guaranteed audio frames. Image and video run() submit a durable job, poll it and return a JobResult with artifacts and bytes(). A polling timeout does not cancel the job; InfimalError.details carries its job_id.
client.model(id)(input) also works directly: it reads the listing’s kinds from GET /v1/models and picks the first fluent surface it supports, in the order chat, embeddings, speech, images, video.
max_tokens() caps output tokens, not dollars. No request deadline, throughput target or cost bid is accepted: bid() raises NotImplementedError. LoRA selection and output shapes must be supported by the deployed listing and runtime.
from infimal import Client client = Client.from_env()chat = client.model("qwen3-8b")print(chat.chat("Explain this code.").max_tokens(128).run().text)for text in chat.chat("Summarize it.").max_tokens(64).stream(): print(text, end="", flush=True) vectors = client.model("your-embedding-listing").embeddings(["coast", "city"]).run()audio = client.model("your-speech-listing").speech("Hello.").speaker("alloy").run()image = client.model("your-image-listing").images("A paper boat.").preset("I1").seed(42).run()open("boat.png", "wb").write(image.bytes())Reference images without an inline body
create_upload() returns a tenant-scoped key, a signed PUT URL and required headers. PUT exactly the declared byte count and content type without your API key, then use reference_key(). PNG, JPEG and WebP are accepted. URLs expire after 15 minutes; input objects are pruned after 24 hours. The default limit is 32 MiB per upload, configurable with INFIMAL_MAX_UPLOAD_MIB up to 128 MiB.
The API validates the reference before reserving credit and reads it again before dispatch. Missing, oversized or malformed objects are refused; replacement after submission fails the job and refunds its hold. reference(path_or_bytes) remains available for inline base64 images. Uploaded inputs and generated artifacts have separate namespaces.
from pathlib import Pathimport httpxfrom infimal import Client client = Client.from_env()data = Path("reference.png").read_bytes()upload = client.create_upload("image/png", len(data))httpx.put(upload["url"], content=data, headers=upload["headers"]).raise_for_status()image = (client.model("your-image-listing").images("A product portrait.") .preset("I1").reference_key(upload["key"]).seed(42).run())Chat
client.model(id) returns a handle; .chat() builds one request. run() streams the completion under the hood and hands back the assembled text and usage.
max_tokens caps output tokens, not a dollar amount. system() replaces a leading system message, or inserts one.
from infimal import Client client = Client.from_env()chat = client.model("qwen3-8b") result = ( chat.chat("Explain this diff.") .system("Answer in one paragraph.") .temperature(0.4) .max_tokens(256) .run())print(result.text, result.usage, result.request_id)Images
Images and video are jobs: run() submits, polls and returns the artifacts. loras() applies the listing’s own resident adapters by name and weight.
capabilities() reports the listing’s LoRAs, defaults and readiness before you call it.
from infimal import Client client = Client.from_env()portraits = client.model("your-image-listing") image = ( portraits.images("A portrait in soft afternoon light.") .preset("I1") .loras({"editorial": 0.8}) .seed(42) .run())open("portrait.png", "wb").write(image.bytes())Video
submit() returns a Job without waiting. A process that restarts adopts it again with client.job(id); wait(), refresh() and cancel() are the job’s own methods.
priority() is "interactive" (the default) or "background". idempotency() makes a retry return the job already held instead of opening a second one.
from infimal import Client client = Client.from_env()job = ( client.model("your-video-listing") .video("A paper boat in a neon-lit city.") .preset("V5") .frames(81, fps=16) .seed(7) .priority("background") .idempotency("take-1") .submit())job.wait(timeout_s=900)open("clip.mp4", "wb").write(job.artifacts[0].bytes())Voice
run() returns the whole file; stream() yields transport chunks as they arrive, not guaranteed audio frames.
speed() takes 0.25 to 4. There is no bid on first-audio latency: request terms wait on the fee-vector work (docs/sdk.md).
from infimal import Client client = Client.from_env()audio = ( client.model("your-speech-listing") .speech("Your next adventure starts here.") .speaker("alloy") .speed(1.1) .run())open("line.mp3", "wb").write(audio)Embeddings
One request, one submission: embeddings() accepts a string or a list and returns vectors in input order.
There is no separate batching declaration to author; send the batch you want embedded.
from infimal import Client client = Client.from_env()vectors = ( client.model("your-embedding-listing") .embeddings(["The quiet coast.", "A city after rain."]) .run())Options by surface
Every modifier validates its own arguments — units, ranges and allowed values — before anything is sent, and raises if it does not apply to the request’s surface. extra(fields) sends wire fields that have no builder method, but the engine refuses one it does not know; it is not a way around validation.
| Method | Surfaces | What it does |
|---|---|---|
| max_tokens(n) | chat | Caps output tokens; not a dollar ceiling. |
| system(text) | chat | Replaces a leading system message, or inserts one. |
| temperature(x) | chat | 0 to 2. |
| json() | chat | Asks for response_format json_object. Not every model honours it. |
| speaker(voice) | speech | Voice name; the request defaults to "alloy" if unset. |
| speed(x) | speech | 0.25 to 4. |
| size(width, height) | images, video | 1 to 4096 each. |
| seed(n) | images, video | 0 to 2^32-1. |
| steps(n) | images, video | 1 to 200. |
| guidance(x) | images, video | 0 to 100. |
| negative(text) | images, video | Sets negative_prompt. |
| loras({name: weight}) | images, video | The listing’s resident LoRAs. {} asks for none, which is not the same as omitting the call. |
| with_lora(name, strength) | images | One Hub adapter, applied whole. |
| reference(value, role) | images, video | An inline reference image, base64-encoded. |
| reference_key(key, role) | images, video | An uploaded reference by its create_upload() key. role on a video job is "reference" or "first_frame". |
| n(n) | images | 1 to 4 images per call. |
| preset(name) | images, video | "I1"/"I2"/"I4" for images, "V5"/"V10" for video. |
| frames(n, fps=16) | video | 1 to 4096 frames, 1 to 240 fps. |
| priority(name) | images, video | "interactive" (the default) or "background". |
| idempotency(key) | images, video | A resubmit with the same key returns the job already held. |
| extra(fields) | any | Wire fields with no builder method; the engine refuses one it does not know. |
| bid(…) | — | Raises NotImplementedError. Request terms wait on the admission contract (docs/sdk.md). |
Validation and the one-submission rule
- A Request is one submission: run(), stream() or submit() may be called once; reusing it raises.
- A job you lose track of is not lost: client.job(id) adopts it again by id, client.jobs(limit) lists recent ones, and idempotency(key) makes a resubmit return the job already held instead of opening a second one.
- A polling timeout on run() does not cancel the job; the raised error’s details carry its job_id so a caller can adopt it.
- capabilities() (GET /v1/models/{id}) reports a listing’s kinds, reference mode, video timing, resident LoRAs and whether anything is currently ready to serve it — read before you build a request that assumes any of that.
- Every failure is an InfimalError carrying the control plane’s status, code, message, next and details; branch on code, never on the message text.