segmind 1.1.0

Python SDK for Segmind API

Segmind Python SDK

A Python client library for interacting with Segmind APIs, providing easy access to model inference, PixelFlows, webhooks, file uploads, and more.

Installation

pip install segmind

export SEGMIND_API_KEY="your_api_key_here"

Quick Start

import segmind

# Generate an image (sync — single blocking v1 call)
response = segmind.run_sync(
    "seedream-v3-text-to-image",
    prompt="A beautiful sunset over mountains",
    aspect_ratio="16:9"
)

# Save the image
with open("sunset2.jpg", "wb") as f:
    f.write(response.content)

⚠️ 1.1.0 breaking change — verbs were redefined. run is now the async (v2, queue-backed) path and returns a result dict; the old synchronous behaviour moved to run_sync (returns an httpx.Response); run_async was removed (use run). See CHANGELOG.md.

# Run async (v2 — submit + poll until done), returns a dict
result = segmind.run("seedance-1-pro", prompt="A sunset")

# For long / video models, submit and wait with a custom deadline
job = segmind.submit_async("seedance-1-pro", prompt="A sunset")
result = job.wait(timeout=900)

Core Components

• SegmindClient: Main client for API interactions
• PixelFlows: Workflow execution and management
• Webhooks: Webhook configuration and monitoring
• Files: Media file upload handling
• Generations: Usage analytics and history
• Models: Model discovery and information

Supported Media Formats

Images: png, jpg, jpeg, gif, bmp, webp, svg, ico, tif, tiff, jfif, pjp, apng, svgz, heif, heic, xbm

Audio: mp3, aiff, wma, au

Video: mp4, avi, mov, mkv, wmv, flv, webm, mpeg, mpg

Examples

Text to Image

import segmind

response = segmind.run_sync(
    "seedream-v3-text-to-image",
    prompt="A cyberpunk cityscape at night",
    aspect_ratio="16:9"
)

with open("image.jpg", "wb") as f:
    f.write(response.content)

LLM Chat

import segmind

# Async by default; .text is normalized across OpenAI / Anthropic / Gemini
reply = segmind.chat("gpt-5.5", prompt="Write a haiku about the sea")
print(reply.text)
print(reply.usage, reply.finish_reason)

# Sync single call
reply = segmind.chat_sync("claude-4.5-sonnet", messages=[
    {"role": "user", "content": "Summarize the plot of Dune in one line"},
])

# Multimodal: image_url() inlines a local file as a base64 data-URI
msg = {"role": "user", "content": [
    {"type": "text", "text": "What's in this image?"},
    segmind.image_url("cat.png"),
]}
reply = segmind.chat("gpt-5.5", messages=[msg])

PixelFlows

import segmind

result = segmind.pixelflows.run(
    workflow_id="your-workflow-id",
    data={"prompt": "Generate an infographic"},
    poll=True
)

File Upload

import segmind

# Upload a file to Segmind Storage
result = segmind.files.upload("path/to/image.png")
print(result["file_urls"][0])
# https://images.segmind.com/assets/...

# Batch upload multiple files
result = segmind.files.upload(["image1.png", "image2.jpg"])
for url in result["file_urls"]:
    print(url)

Webhooks

import segmind

# Add a webhook
segmind.webhooks.add("https://your-endpoint.com", ["PIXELFLOW"])

# Get all webhooks
webhooks = segmind.webhooks.get()

Finetuning

from segmind import SegmindClient

client = SegmindClient()

# Get a presigned URL to upload your dataset (.zip)
upload = client.finetune.upload_presigned_url(name="my-dataset.zip")
# upload["presigned_url"] can be used with a PUT request to S3

# Submit a fine-tune request
job = client.finetune.submit(
    name="flux-job-1",
    data_source_path=upload["s3_url"],  # or any public zip URL
    instance_prompt="1MAN, running in brown suit",
    trigger_word="1MAN",
    base_model="FLUX",
    train_type="LORA",
    machine_type="NVIDIA_A100_40GB",
    theme="FLUX",
    segmind_public=False,
    advance_parameters={
        "steps": 1000,
        "batch_size": 2,
        "learning_rate": 4e-4,
    },
)

# Get details
details = client.finetune.details(request_id=job["finetune_id"])

# List all
all_jobs = client.finetune.list()

# Update access (public/private)
client.finetune.access_update(request_id=job["finetune_id"], segmind_public=True)

# Download model file (returns a temporary URL string)
download_url = client.finetune.file_download(cloud_storage_url=details["finetune"]["cloud_storage_url"])

Documentation

For detailed examples and API reference, see examples.md.

Public API Playground (Swagger UI): open docs/swagger.html after building docs, or serve docs/ statically. It loads the spec at docs/_static/openapi/segmind-sdk.yaml and supports the Authorize flow with x-api-key.

Run this to serve the documentation:

cd docs && python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

Requirements

• Python 3.8+
• httpx
• typing-extensions (for Python < 3.10)

Error Handling

The SDK provides comprehensive error handling with detailed error messages:

import segmind
from segmind.exceptions import SegmindError

try:
    response = segmind.run_sync("invalid-model", prompt="test")
except SegmindError as e:
    print(f"API Error: {e.detail}")
    print(f"Status Code: {e.status}")

Development

Setup Development Environment

1. Clone the repository:

   git clone https://github.com/segmind/segmind-python.git
   cd segmind-python
   

2. Install development dependencies:

   pip install -e ".[test,dev]"
   

3. Install pre-commit hooks:

   pre-commit install
   

Running Tests

# Run all tests
make test

# Run with coverage
make test-coverage

# Run verbose
make test-verbose

Linting and Formatting

# Run all pre-commit checks
make lint

# Or run pre-commit directly
pre-commit run --all-files

Building the Package

# Build distribution packages
make build

# Build and check with twine
make build-check

Releasing

For information on creating releases and publishing to PyPI, see RELEASING.md.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: make test
5. Ensure code quality: pre-commit run --all-files
6. Submit a pull request

See CONTRIBUTING.md for detailed contribution guidelines.

License

This project is licensed under the MIT License.

Support

For support and questions:

• GitHub Issues: Report bugs or request features
• Documentation: API Documentation
• Examples: See examples.md for comprehensive usage examples