English | 简体中文

This repository contains the official client libraries for sunra.ai, a platform for deploying and running AI models. The libraries provide robust and user-friendly interfaces for integrating sunra.ai endpoints into your applications across multiple programming languages.

• Location: clients/python/
• Package: sunra-client (PyPI)
• Features: Synchronous and asynchronous support, streaming responses, file uploads
• Installation: pip install sunra-client

• Location: clients/javascript/
• Package: @sunra/client (npm)
• Features: Works in Web, Node.js, and React Native environments
• Installation: npm install @sunra/client

• Location: clients/java/
• Package: ai.sunra.client:sunra-client (Maven Central)
• Features: Synchronous, asynchronous, and Kotlin coroutine support
• Installation: implementation "ai.sunra.client:sunra-client:0.1.6"

Before using any client library, you'll need to:

1. Sign up at sunra.ai
2. Get your API key from the dashboard
3. Set your API key as an environment variable: export SUNRA_KEY=your-api-key

import sunra_client

# Simple synchronous call
result = sunra_client.subscribe(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={"prompt": "a cute cat, realistic, orange"}
)
print(result["images"][0]["url"])

# Asynchronous call
async def main():
    result = await sunra_client.subscribe_async(
        "black-forest-labs/flux-kontext-pro/text-to-image",
        arguments={"prompt": "a cute cat, realistic, orange"}
    )
    print(result["images"][0]["url"])

import { createSunraClient } from "@sunra/client";

const sunra = createSunraClient({
  credentials: process.env.SUNRA_KEY,
});

const result = await sunra.subscribe(
  "black-forest-labs/flux-kontext-pro/text-to-image",
  {
    input: {
      prompt: "a cute cat, realistic, orange"
    }
  }
);
console.log(result.images[0].url);

import ai.sunra.client.*;

var sunra = SunraClient.withEnvCredentials();

var result = sunra.subscribe(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    SubscribeOptions.<JsonObject>builder()
        .input(Map.of("prompt", "a cute cat, realistic, orange"))
        .resultType(JsonObject.class)
        .build()
);
System.out.println(result.getData());

For client-side applications, we provide a server proxy to securely handle API calls without exposing your credentials. Available for popular frameworks:

• Location: server-proxy/
• Package: @sunra/server-proxy (npm)
• Supports: Next.js, Express, Hono, Remix, SvelteKit

The MCP server provides a universal interface for AI model tools, enabling seamless integration with modern code assistants and IDEs such as Cursor and Claude Desktop. It acts as a bridge between Sunra.ai and your development environment, exposing Sunra's models and tools via the Model Context Protocol.

Why use the MCP server?

• Enables code assistants (like Cursor, Claude, etc.) to access Sunra models and tools directly from your editor
• Supports listing models, fetching schemas, submitting jobs, streaming results, and more
• Secure: API keys are managed via environment variables or runtime configuration
• No need to write glue code—just run the server and connect your tool

npx @sunra/mcp-server --transport http --port 3925

• Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "sunra-mcp-server": {
      "url": "http://localhost:3925/sse"
    }
  }
}

• Set your API key:

  export SUNRA_KEY="your-api-key-here"

• In Cursor, select the sunra-mcp-server and use tools like list-models, model-schema, etc.

• Start the server in stdio mode (default):

  npx @sunra/mcp-server

• In Claude Desktop settings, add a new MCP server:
  • Type: Local executable
  • Command: npx @sunra/mcp-server
  • Environment Variables:

    SUNRA_KEY=your-api-key-here
    

• In Claude, select the sunra-mcp-server and use the available tools.

• See mcp-server/README.md for full tool list, development, and troubleshooting.

The repository includes comprehensive examples for different frameworks and use cases:

• Next.js Apps: examples/demo-nextjs-app-router/ and examples/demo-nextjs-page-router/
• Node.js: examples/demo-nodejs/
• Express: examples/demo-express-app/
• Java: examples/demo-java/
• Java Async: examples/demo-java-async/
• Kotlin: examples/demo-kotlin/
• Python: examples/demo-python/

To set up the development environment:

1. Clone the repository
2. Install dependencies: pnpm i -r
3. Set up your API key: export SUNRA_KEY=your-api-key
4. Run examples or tests as needed

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Make sure you read our Code of Conduct
2. Fork the project and clone your fork
3. Setup the local environment with npm install
4. Create a feature branch (git checkout -b feat/add-cool-thing) or a bugfix branch (git checkout -b fix/smash-that-bug)
5. Commit the changes (git commit -m 'feat(client): added a cool thing') - use conventional commits
6. Push to the branch (git push --set-upstream origin feat/add-cool-thing)
7. Open a Pull Request

Check the good first issue queue, your contribution will be welcome!

Distributed under the Apache 2.0 License. See LICENSE for more information.

This project is derived from:

• fal-ai/fal-js
• fal-ai/fal-java
• fal-ai/fal

and adapted to work with sunra.ai. The original projects are licensed under the MIT/Apache 2.0 License. We extend our gratitude to the original authors for their contributions.