Predictions — Hypery Docs

Overview

The Predictions API provides async execution for models from Replicate, a platform for running ML models in the cloud. Our gateway uses 100% Replicate-compatible format, so you can use the official Replicate SDK or plain HTTP.

Authentication: API Key or OAuth token
Required Scopes (OAuth): ai:images (for image models), ai:predictions (general)

Replicate hosts thousands of open-source ML models including:

Image Generation - Flux, Stable Diffusion, DALL-E
Video Generation - Stable Video, AnimateDiff
Image Enhancement - Upscaling, restoration, editing
Text-to-Speech - Voice generation
Custom Models - Community-built models

Use Predictions for models that:

Take 10+ seconds to run
Generate images, videos, or audio
Need async execution (start now, check later)

For fast chat models (< 1 second), use the Chat API instead.

How It Works

Async Flow:

Create → Get prediction ID immediately
Poll → Check status every few seconds
Complete → Get output when status === "succeeded"

Create Prediction

Start an async prediction.

Endpoint: POST /api/v1/predictions

import Replicate from 'replicate'
 
const replicate = new Replicate({
  auth: 'YOUR_API_KEY',
  baseUrl: 'https://hypery.ai/api/v1'
})
 
const prediction = await replicate.predictions.create({
  model: 'black-forest-labs/flux-schnell',
  input: {
    prompt: 'a cat wearing sunglasses'
  }
})
 
console.log(prediction.id)

const response = await fetch('https://hypery.ai/api/v1/predictions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'black-forest-labs/flux-schnell',
    provider: 'replicate',
    input: {
      prompt: 'a cat wearing sunglasses'
    }
  })
})
 
const prediction = await response.json()
console.log(prediction.id)

import replicate
 
client = replicate.Client(
    api_token='YOUR_API_KEY',
    base_url='https://hypery.ai/api/v1'
)
 
prediction = client.predictions.create(
    model='black-forest-labs/flux-schnell',
    input={'prompt': 'a cat wearing sunglasses'}
)
 
print(prediction.id)

import requests
 
response = requests.post(
    'https://hypery.ai/api/v1/predictions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'black-forest-labs/flux-schnell',
        'provider': 'replicate',
        'input': {'prompt': 'a cat wearing sunglasses'}
    }
)
 
prediction = response.json()
print(prediction['id'])

curl -X POST https://hypery.ai/api/v1/predictions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/flux-schnell",
    "provider": "replicate",
    "input": {
      "prompt": "a cat wearing sunglasses"
    }
  }'

Response:

{
  "id": "abc123",
  "status": "starting"
}

Get Prediction

Check if it's done.

Endpoint: GET /api/v1/predictions/:id

const prediction = await replicate.predictions.get('abc123')
 
console.log(prediction.status)   // "processing" or "succeeded"
console.log(prediction.output)   // Image URL when done

const response = await fetch(
  'https://hypery.ai/api/v1/predictions/abc123',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
)
 
const prediction = await response.json()
console.log(prediction.status)
console.log(prediction.output)

prediction = client.predictions.get('abc123')
 
print(prediction.status)   # "processing" or "succeeded"  
print(prediction.output)   # Image URL when done

response = requests.get(
    'https://hypery.ai/api/v1/predictions/abc123',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
 
prediction = response.json()
print(prediction['status'])
print(prediction['output'])

curl https://hypery.ai/api/v1/predictions/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (succeeded):

{
  "id": "abc123",
  "status": "succeeded",
  "output": ["https://...image.jpg"],
  "metrics": {
    "predict_time": 12.5
  }
}

Output Fields

Field	Type	Description
`id`	string	Prediction identifier
`status`	string	Current status (see status values below)
`output`	array \| null	Generated images (URLs) when succeeded
`error`	string \| null	Error message when failed
`metrics`	object	Performance data (predict_time in seconds)
`created_at`	string	When prediction was created
`started_at`	string \| null	When processing started
`completed_at`	string \| null	When prediction finished

Wait for Completion

Poll until done (with the SDK, this is automatic).

// SDK handles polling automatically
const output = await replicate.run(
  'black-forest-labs/flux-schnell',
  { input: { prompt: 'a sunset' } }
)
 
console.log(output[0])  // Image URL

async function wait(id) {
  while (true) {
    const res = await fetch(
      `https://hypery.ai/api/v1/predictions/${id}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    )
    const data = await res.json()
    
    if (data.status === 'succeeded') return data.output
    if (data.status === 'failed') throw new Error(data.error)
    
    await new Promise(r => setTimeout(r, 1000))
  }
}
 
// Usage
const output = await wait('abc123')

# SDK handles polling automatically
output = client.run(
    'black-forest-labs/flux-schnell',
    input={'prompt': 'a sunset'}
)
 
print(output[0])  # Image URL

import time
 
def wait(prediction_id):
    while True:
        res = requests.get(
            f'https://hypery.ai/api/v1/predictions/{prediction_id}',
            headers={'Authorization': 'Bearer YOUR_API_KEY'}
        )
        data = res.json()
        
        if data['status'] == 'succeeded':
            return data['output']
        if data['status'] == 'failed':
            raise Exception(data['error'])
        
        time.sleep(1)
 
# Usage
output = wait('abc123')

The Replicate SDK automatically polls for you. With fetch/requests, you need to poll manually.

Input Options

Customize your generation:

Option	Type	Default	Description
`prompt`	string	Required	What to generate
`width`	number	1024	Image width
`height`	number	1024	Image height
`num_outputs`	number	1	How many images (1-4)

Example:

{
  "input": {
    "prompt": "a sunset",
    "width": 1024,
    "height": 768,
    "num_outputs": 2
  }
}

Status Values

Status	Meaning	Next Step
`starting`	Queued	Keep polling
`processing`	Running	Keep polling
`succeeded`	Done ✓	Get output
`failed`	Error ✗	Check error

SDK Setup

Install the Replicate SDK:

npm install replicate

pip install replicate

Configure it to use Hypery:

import Replicate from 'replicate'
 
const replicate = new Replicate({
  auth: process.env.GATEWAY_API_KEY,
  baseUrl: 'https://hypery.ai/api/v1'
})

import replicate
 
client = replicate.Client(
    api_token=os.getenv('GATEWAY_API_KEY'),
    base_url='https://hypery.ai/api/v1'
)

Common Errors

Code	Error	Fix
401	Unauthorized	Check API key
429	Out of credits	Add credits
400	Invalid model	Check model name

Next Steps

Image API

Overview of image generation options

Models

Browse available models