Skip to content

feat: Public endpoints documentation #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -27,4 +27,6 @@ yarn-error.log*
helpers/__pycache__/** */

# Webstorm
.idea/*
.idea/*

CLAUDE.md
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@
"group": "Hub",
"pages": [
"hub/overview",
"hub/public-endpoints",
"hub/publishing-guide"
]
},
Expand Down
14 changes: 13 additions & 1 deletion hub/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ The Hub operates through several key components working together:

1. **Repository integration**: The Hub connects with GitHub repositories, using GitHub releases (not commits) as the basis for versioning and updates.
2. **Configuration system**: Repositories use standardized configuration files (`hub.json` and `tests.json`) in a `.runpod` directory to define metadata, hardware requirements, and test procedures. See the [publishing guide](/hub/publishing-guide) to learn more.
3. **Automated build pipeline**: When a repository is submitted or updated, the Hub automatically scans, builds, and tests it to ensure it works correctly on RunPods infrastructure.
3. **Automated build pipeline**: When a repository is submitted or updated, the Hub automatically scans, builds, and tests it to ensure it works correctly on RunPod's infrastructure.
4. **Continuous release monitoring**: The system regularly checks for new releases in registered repositories and rebuilds them when updates are detected.
5. **Deployment interface**: Users can browse repos, customize parameters, and deploy them to RunPod infrastructure with minimal configuration.

Expand Down Expand Up @@ -74,6 +74,18 @@ Once your endpoint is ready to share:

To learn more, see the [Hub publishing guide](/hub/publishing-guide).

## Public endpoints

In addition to offering official and community-submitted repos, the Hub also offers public endpoints for popular AI models. These are ready-to-use APIs that you can integrate directly into your applications without needing to manage the underlying infrastructure.

Public endpoints provide:

- Instant access to state-of-the-art models.
- A playground for interactive testing.
- Simple, usage-based pricing.

To learn more about available models and how to use them, see [Public endpoints](/hub/public-endpoints).

## Use cases

The RunPod Hub supports a wide range of AI applications and workflows. Here are some common use cases that demonstrate the versatility and power of Hub repositories:
Expand Down
248 changes: 248 additions & 0 deletions hub/public-endpoints.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
---
title: "Public endpoints"
sidebarTitle: "Public endpoints"
description: "Test and deploy production-ready AI models using public endpoints."
---

<Note>
**Public endpoints are currently in beta.** We're actively expanding our model selection and working to improve the user experience. [Join our Discord](https://discord.gg/runpod) if you'd like to provide feedback.
</Note>

RunPod public endpoints provide instant access to state-of-the-art AI models through simple API calls.

## Available models

Our initial launch includes optimized text-to-image generation models:

| Model | Description | Endpoint URL |
|-------|-------------|----------|
| **Flux Dev** | High-quality image generation with excellent prompt adherence | `https://api.runpod.ai/v2/black-forest-labs-flux-1-dev/` |
| **Flux Schnell** | Fast image generation optimized for speed | `https://api.runpod.ai/v2/black-forest-labs-flux-1-schnell/` |

## Public endpoint playground

The public endpoint playground provides a streamlined way to discover and experiment with AI models.

The playground offers:

- **Interactive parameter adjustment**: Modify prompts, dimensions, and model settings in real-time.
- **Instant preview**: Generate images directly in the browser.
- **Cost estimation**: See estimated costs before running generation.
- **API code generation**: Create working code examples for your applications.

### Access the playground

1. Navigate to the [RunPod Hub](https://www.runpod.io/console/hub) in the console.
2. Find the **Public endpoints** section.
3. Use the dropdown menu to browse available models and select one that fits your needs.

### Test a model

To test a model in the playground:

1. Select a model using the dropdown menu.
2. Under **Input**, enter a prompt in the text box.
3. Enter a negative prompt if needed. Negative prompts tell the model what to exclude from the output.
4. Under **Additional settings**, you can adjust the seed, aspect ratio, number of inference steps, guidance scale, and output format.
5. Click **Run** to start generating.

Under **Result**, you can use the dropdown menu to show either a preview of the output, or the raw JSON.

### Create a code example

After inputting parameters using the playground, you can automatically generate an API request to use in your application.

1. Select the **API** tab in the UI (above the **Input** field).
2. Using the dropdown menu, select the programming language (Python, JavaScript, cURL, etc.) and POST command you want to use (`/run` or `/runsync`).
3. Copy the code example to your clipboard.

## Make API requests to public endpoints

You can make API requests to public endpoints using any HTTP client. The endpoint URL is specific to the model you want to use.

All requests require authentication using your RunPod API key, passed in the `Authorization` header. You can find and create [API keys](/get-started/api-keys) in the [RunPod console](https://www.runpod.io/console/user/settings) under **Settings > API Keys**.

<Tip>
To learn more about the difference between synchronous and asynchronous requests, see [Endpoint operations](/serverless/endpoints/operations).
</Tip>

### Synchronous request example

Here's an example of a synchronous request to Flux Dev using the `/runsync` endpoint:

```bash curl
curl -X POST "https://api.runpod.ai/v2/black-forest-labs-flux-1-dev/runsync" \
-H "Authorization: Bearer RUNPOD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"prompt": "A serene mountain landscape at sunset",
"width": 1024,
"height": 1024,
"num_inference_steps": 20,
"guidance": 7.5
}
}'
```

### Asynchronous request example

Here's an example of an asynchronous request to Flux Dev using the `/run` endpoint:

```bash curl
curl -X POST "https://api.runpod.ai/v2/black-forest-labs-flux-1-dev/run" \
-H "Authorization: Bearer RUNPOD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"prompt": "A futuristic cityscape with flying cars",
"width": 1024,
"height": 1024,
"num_inference_steps": 50,
"guidance": 8.0
}
}'
```

You can check the status and retrieve results using the `/status` endpoint, replacing `{job-id}` with the job ID returned from the `/run` request:

```bash curl
curl -X GET "https://api.runpod.ai/v2/black-forest-labs-flux-1-dev/status/{job-id}" \
-H "Authorization: Bearer RUNPOD_API_KEY"
```

### Response format

All endpoints return a consistent JSON response format:

```json
{
{
"delayTime": 17,
"executionTime": 3986,
"id": "sync-0965434e-ff63-4a1c-a9f9-5b705f66e176-u2",
"output": {
"cost": 0.02097152,
"image_url": "https://image.runpod.ai/gen-images/6/6/mCwUZlep6S/453ad7b7-67c6-43a1-8348-3ad3428ef97a.png",
"message": "Image generated successfully",
"status": "success"
},
"status": "COMPLETED",
"workerId": "oqk7ao1uomckye"
}
```

## Model-specific parameters

Each endpoint accepts a different set of parameters to control the generation process.

### Flux Dev

Flux Dev is optimized for high-quality, detailed image generation. The model accepts several parameters to control the generation process:

```json
{
"input": {
"prompt": "A serene mountain landscape at sunset",
"negative_prompt": "Snow",
"width": 1024,
"height": 1024,
"num_inference_steps": 20,
"guidance": 7.5,
"seed": 42,
"image_format": "png"
}
}
```

**Parameters:**
- `prompt` (string, required): Text description of the desired image.
- `negative_prompt` (string, optional): Elements to exclude from the image.
- `width` (integer, default: 1024): Image width in pixels (64-2048).
- `height` (integer, default: 1024): Image height in pixels (64-2048).
- `num_inference_steps` (integer, default: 20): Number of denoising steps (1-50).
- `guidance` (float, default: 7.5): How closely to follow the prompt (1.0-20.0).
- `seed` (integer, optional): Random seed for reproducible results.
- `image_format` (string, default: "jpeg"): Output format ("png" or "jpeg").

### Flux Schnell

Flux Schnell is optimized for speed and real-time applications:

```json
{
"input": {
"prompt": "A quick sketch of a mountain",
"width": 1024,
"height": 1024,
"num_inference_steps": 4,
"guidance": 1.0,
"seed": 123
}
}
```

**Parameters:**
- `prompt` (string, required): Text description of the desired image.
- `width` (integer, default: 1024): Image width in pixels (64-2048).
- `height` (integer, default: 1024): Image height in pixels (64-2048).
- `num_inference_steps` (integer, default: 4): Number of denoising steps (1-8).
- `guidance` (float, default: 1.0): Prompt adherence strength (0.5-2.0).
- `seed` (integer, optional): Random seed for reproducible results.

<Warning>
Flux Schnell is optimized for speed and works best with lower step counts. Using higher values may not improve quality significantly.
</Warning>

## Python example

Here is an example Python API request to Flux Dev using the `/run` endpoint:

```python
import requests

headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer RUNPOD_API_KEY'
}

data = {
'input': {"prompt":"A serene mountain landscape at sunset","image_format":"png","num_inference_steps":25,"guidance":7,"seed":50,"width":1024,"height":1024}
}

response = requests.post('https://api.runpod.ai/v2/black-forest-labs-flux-1-dev/run', headers=headers, json=data)
```

You can generate public endpoint API requests for Python and other programming languages using the [public endpoint playground](#public-endpoint-playground).

## Pricing

Public endpoints use transparent, usage-based pricing:

| Model | Price | Billing unit |
|-------|-------|--------------|
| Flux Dev | $0.02 | Per megapixel |
| Flux Schnell | $0.00024 | Per megapixel |

**Pricing examples:**
- 512×512 image (0.25 megapixels): \$0.005 (Flux Dev) / \$0.00006 (Flux Schnell)
- 1024×1024 image (1 megapixel): \$0.02 (Flux Dev) / \$0.00024 (Flux Schnell)
- 2048×2048 image (4 megapixels): \$0.08 (Flux Dev) / \$0.00096 (Flux Schnell)

<Note>
Pricing is calculated based on the actual output resolution. You will not be charged for failed generations.
</Note>

## Best practices

When working with public endpoints, following best practices will help you achieve better results and optimize performance.

### Prompt engineering

For prompt engineering, be specific with detailed prompts as they generally produce better results. Include style modifiers such as art styles, camera angles, or lighting conditions. For Flux Dev, use negative prompts to exclude unwanted elements from your images.

A good prompt example would be: "A professional portrait of a woman in business attire, studio lighting, high quality, detailed, corporate headshot style."

### Performance optimization

For performance optimization, choose the right model for your needs. Use Flux Schnell when you need speed, and Flux Dev when you need higher quality. Standard dimensions like 1024×1024 render fastest, so stick to these unless you need specific aspect ratios. For multiple images, use asynchronous endpoints to batch your requests. Consider caching results by storing generated images to avoid regenerating identical prompts.