Python SDK

The Segmind Python SDK is a thin client over the AI Gateway. As of 1.1.0 it is async-by-default: run() submits to the v2 async API, polls for you, and returns the finished result. A blocking v1 call is still available as run_sync().

Install

pip install "segmind>=1.4.0"

Set your API key once via the environment:

export SEGMIND_API_KEY="YOUR_API_KEY"

The SDK reads SEGMIND_API_KEY automatically. Grab a key from the API Keys page.

Sync vs. async — which to use?

Quick start

import segmind

# Submit to v2, poll until COMPLETED, return the result body.
result = segmind.run("seedream-4.5", prompt="a red rose on a wooden table")
print(result["output"])  # URL to the generated image

import segmind

# Single blocking v1 call — returns a raw httpx.Response.
response = segmind.run_sync("seedream-4.5", prompt="a red rose on a wooden table")
with open("rose.jpg", "wb") as f:
    f.write(response.content)

API

segmind.run(slug, **params) -> dict

Async by default. Submits to POST /v2/{slug}, polls until the request reaches COMPLETED, and returns the final response body as a dict. Polls every 1 s with a 600 s deadline.

result = segmind.run("seedream-4.5", prompt="a sunset over the ocean")
print(result["output"])

segmind.run_sync(slug, **params)

Synchronous, single blocking call to POST /v1/{slug}. Returns the raw httpx.Response — use .content for binary output (images, audio) or .json() for structured responses.

response = segmind.run_sync("sdxl1.0-newreality-lightning", prompt="a cyberpunk city")
with open("city.jpg", "wb") as f:
    f.write(response.content)

segmind.submit_async(slug, **params) -> AsyncJob

Submits a v2 request and returns an AsyncJob handle immediately, without waiting for the result. Use it to control the poll deadline/cadence, to keep the request_id, or to run other work while the job processes.

job = segmind.submit_async("seedance-2.0", prompt="a sunset timelapse")
print(job.request_id)          # e.g. "2c7f59ea-13f1-402c-9353-915a2b5a2124"
result = job.wait(timeout=600) # block until done

AsyncJob

The handle returned by submit_async().

import time
import segmind

job = segmind.submit_async("seedance-2.0", prompt="a sunset timelapse")

# Manual polling, if you want it:
while job.status()["status"] not in ("COMPLETED", "FAILED"):
    time.sleep(2)

result = job.result()

Error handling

run() and AsyncJob.wait() raise on failure:

import segmind
from segmind import InferenceFailed, InferenceTimeout

try:
    result = segmind.run("seedream-4.5", prompt="a red rose")
except InferenceFailed as e:
    print(f"Model failed: {e.detail}")
except InferenceTimeout as e:
    print(f"Still running after {e.elapsed_s:.0f}s — request {e.request_id}")

Worked examples

Fast image model

For a quick image model the defaults are all you need — run() typically returns after a single poll.

import segmind

result = segmind.run("seedream-4.5", prompt="a red rose on a wooden table, studio lighting")
print(result["output"])  # https://images.segmind.com/generations/...jpeg

Slow video model

Video generation can run for several minutes. Because run() caps the wait at 600 s, use submit_async() and pass a larger timeout (and a slower interval to reduce poll traffic):

import segmind
from segmind import InferenceFailed, InferenceTimeout

job = segmind.submit_async("seedance-2.0", prompt="a sunset timelapse over the ocean")
print(f"Submitted {job.request_id}")

try:
    result = job.wait(timeout=900, interval=5)  # up to 15 min, poll every 5s
    print(result["output"])  # URL to the generated video
except InferenceTimeout as e:
    print(f"Not done after {e.elapsed_s:.0f}s — poll {job.status_url} later")
except InferenceFailed as e:
    print(f"Failed: {e.detail}")

LLM chat

For text/LLM models, chat() returns a normalized ChatResponse with a provider-agnostic .text. It's async-by-default like run(), with chat_sync() and submit_chat() counterparts.

import segmind

reply = segmind.chat("gpt-5.5", prompt="Write a haiku about the sea")
print(reply.text)

ChatResponse exposes .text, .json(), .tool_calls, .usage, and .raw. Streaming is not supported by the gateway. See the v2 async reference for the underlying response shape.

Beyond inference

run() and chat() are the SDK's main event, but it also ships a handful of namespaces that wrap the account-level APIs. They are useful and, until now, undocumented.

segmind.models

The live model catalog. Requires segmind ≥ 1.4.0.

import segmind

# One page, 50 models by default
page = segmind.models.list(output="video", sort="cheapest", limit=10)
print(page["total"], page["has_more"])
for model in page["models"]:
    print(model["slug"], model["category"], model["average_cost"])

# Every matching model, reading page after page
videos = segmind.models.list_all(output="video")

# One model, with its parameters
model = segmind.models.get("flux-schnell")
print(model["parameters_schema"])

list() takes these filters as keyword arguments: q, sort (popular, newest, name, cheapest, fastest or relevance), category, modality, input, output, provider, slugs, operations, features, min_popularity, min_category_percentile, min_cost, max_cost, max_latency, is_new, created_after, include_coming_soon and facets. It pages with limit (up to 100) and offset, and returns models, total, limit, offset and has_more.

Each entry carries slug, name, category (imageToVideo, textToImage, …), description, provider, input, output, average_cost, latency_seconds and is_new. average_cost is observed spend per request, not the list price. Only get() returns parameters_schema.

To check a slug you depend on, pass it to list(slugs=[...]), which also finds models the catalog doesn't list. A slug it doesn't return isn't available.

The same data is public over REST, with no API key: GET https://api.segmind.com/models and GET https://api.segmind.com/model/<slug>.

segmind.generations

Your own request history — the same data behind Generations in the console.

page = segmind.generations.list(page=1)
print(page["total_records"], page["total_pages"], page["per_page"])
for row in page["data"]:
    print(row["model_name"], row["created_at"], row["generation_url"])

# or the newest few for one model
segmind.generations.recent("p-image")

list() is paginated and returns total_records, total_pages, current_page, per_page, has_next, has_previous and data. recent() takes a model slug and returns data with request_id, generation_url, created_at and status.

segmind.files.upload(file_paths)

Uploads local files and returns reusable URLs — the Segmind Storage API, with the base64 encoding done for you.

result = segmind.files.upload(["portrait.jpg"])
url = result["file_urls"][0]

segmind.run("some-image-to-image-model", image=url)

Takes a list, returns one URL per file in the same order. The size and pixel-count limits are the same as the underlying API.

segmind.webhooks

Manage webhook registrations without going through the console.

update changes the URL only and keeps the registration's id, signing secret and event types. To change the event types, delete the registration and add a new one.

See Webhooks for the event names.

segmind.pixelflows

Run published PixelFlow workflows without hand-rolling the submit/poll HTTP calls. With the default poll=True it submits, polls, and returns the final result; with poll=False it returns immediately with the request_id and poll_url.

import segmind

result = segmind.pixelflows.run(
    workflow_id="your-workflow-id",
    data={"Text_Prompt": "Generate an infographic"},
    poll=True,               # wait for completion
    poll_interval=5,         # seconds between status checks
    max_wait_time=600,       # give up after 10 minutes
)

# Or split submit and poll:
submitted = segmind.pixelflows.run(workflow_id="your-workflow-id", data={...}, poll=False)
status = segmind.pixelflows.get_status(poll_id=submitted["request_id"])
result = segmind.pixelflows.poll(poll_id=submitted["request_id"], max_wait_time=600)

The result mirrors the Workflow API response shapes (QUEUED / PROCESSING / COMPLETED / FAILED).

Migrating from 1.0.x

1.1.0 flips the default verb to async. Update calls as follows:

run_async() was removed with no alias — importing or calling it raises an error. There is no behavioural change to submit_async().

See also

• API Reference · Async Inference (V2) — the HTTP endpoints the SDK calls.
• Webhooks — get notified instead of polling.
• Authentication — API keys and headers.