This API provides AI-powered image generation using Replicate's Flux model. It supports both authenticated access with the service's built-in token and user-provided Replicate API tokens.

https://your-val-town-url.web.val.run

Use the service's built-in Replicate token by providing the service's AUTH_TOKEN:

curl -H "Authorization: Bearer YOUR_SERVICE_AUTH_TOKEN" \
     "https://your-val-town-url.web.val.run/generate?prompt=a%20beautiful%20sunset"

Provide your own Replicate API token to bypass service authentication. This allows you to use your own Replicate credits and quotas without needing the service's AUTH_TOKEN.

Key Benefits:

• No need for service authentication
• Use your own Replicate credits and limits
• Direct control over API usage
• Bypass service rate limits

Generate an image and redirect to the image URL.

Endpoint: GET /generate

Parameters:

• prompt (required): Text description of the image to generate
• replicate_token (optional): Your Replicate API token

Authentication Options:

• With service token: Include Authorization: Bearer YOUR_SERVICE_AUTH_TOKEN header
• With user token: Include replicate_token parameter (no Authorization header needed)

Examples:

Using service authentication:

curl -H "Authorization: Bearer YOUR_SERVICE_AUTH_TOKEN" \
     "https://your-val-town-url.web.val.run/generate?prompt=a%20cat%20wearing%20sunglasses"

Using your own Replicate token:

curl "https://your-val-town-url.web.val.run/generate?prompt=a%20cat%20wearing%20sunglasses&replicate_token=r8_YOUR_REPLICATE_TOKEN"

Response:

• Status: 302 (Redirect)
• Location header contains the generated image URL

Generate an image and return JSON with image details. Supports both simple prompt format and full Replicate API control.

Endpoint: POST /generate

Request Body Options:

Option 1: Simple Format (Backward Compatible)

{
  "prompt": "a beautiful landscape",
  "replicate_token": "r8_YOUR_REPLICATE_TOKEN" // optional
}

Option 2: Full Replicate API Control (New Feature)

{
  "input": {
    "prompt": "a beautiful landscape",
    "output_format": "png",
    "aspect_ratio": "16:9",
    "num_outputs": 1,
    "guidance_scale": 3.5,
    "num_inference_steps": 4,
    "seed": 12345
  },
  "replicate_token": "r8_YOUR_REPLICATE_TOKEN" // optional
}

Option 3: Full Replicate API with Additional Parameters

{
  "input": {
    "prompt": "a beautiful landscape",
    "output_format": "webp",
    "aspect_ratio": "1:1"
  },
  "webhook": "https://your-webhook-url.com/callback",
  "webhook_events_filter": ["start", "completed"],
  "replicate_token": "r8_YOUR_REPLICATE_TOKEN" // optional
}

Authentication Options:

• With service token: Include Authorization: Bearer YOUR_SERVICE_AUTH_TOKEN header
• With user token: Include replicate_token in request body (no Authorization header needed)
• With user token (header): Include X-Replicate-Token: r8_YOUR_REPLICATE_TOKEN header

Examples:

Using service authentication (simple format):

curl -X POST \
     -H "Authorization: Bearer YOUR_SERVICE_AUTH_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "a futuristic city"}' \
     https://your-val-town-url.web.val.run/generate

Using your own Replicate token (simple format):

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"prompt": "a futuristic city", "replicate_token": "r8_YOUR_REPLICATE_TOKEN"}' \
     https://your-val-town-url.web.val.run/generate

Using full Replicate API control:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "input": {
         "prompt": "a futuristic city at sunset",
         "aspect_ratio": "16:9",
         "output_format": "png",
         "guidance_scale": 3.5,
         "num_inference_steps": 8,
         "seed": 42
       },
       "replicate_token": "r8_YOUR_REPLICATE_TOKEN"
     }' \
     https://your-val-town-url.web.val.run/generate

Using your own Replicate token (in header):

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-Replicate-Token: r8_YOUR_REPLICATE_TOKEN" \
     -d '{
       "input": {
         "prompt": "a futuristic city",
         "aspect_ratio": "1:1",
         "output_format": "webp"
       }
     }' \
     https://your-val-town-url.web.val.run/generate

Response:

{
  "id": "generated_image_1234567890.png",
  "imageUrl": "https://your-val-town-url.web.val.run/image/generated_image_1234567890.png"
}

Get a previously generated image.

Endpoint: GET /image/{imageId}

Parameters:

• imageId: The image ID returned from the generate endpoint

Authentication: None required for image retrieval

Example:

curl https://your-val-town-url.web.val.run/image/generated_image_1234567890.png

Response:

• Content-Type: image/png
• Binary image data

When multiple token sources are provided, the API uses this priority order:

1. X-Replicate-Token header
2. replicate_token in request body (POST only)
3. replicate_token query parameter (GET only)
4. Service's built-in REPLICATE_API_TOKEN (default)

{
  "error": "Missing 'prompt' query parameter"
}

or

{
  "error": "Missing 'prompt' or 'input' in request body. Provide either 'prompt' for simple usage or 'input' object for full Replicate API control."
}

Unauthorized access 🚫

Not Found

or

Image not found

{
  "error": "Failed to generate image",
  "details": "Specific error message"
}

1. Sign up at replicate.com
2. Go to your account settings
3. Generate an API token
4. The token will start with r8_

• Use the built-in authentication to control access
• Monitor usage through your service logs
• Manage costs through your Replicate account

• Use your own Replicate token to:
  • Avoid service rate limits
  • Use your own Replicate credits
  • Have direct control over API usage
  • Bypass service authentication requirements

Rate limits depend on the Replicate token being used:

• Service token: Subject to the service owner's Replicate plan
• User token: Subject to your own Replicate plan and limits

When using the full API control format, you can specify any parameters supported by the black-forest-labs/flux-schnell model:

• prompt (required): Text description of the image
• aspect_ratio: Image dimensions (e.g., "1:1", "16:9", "9:16", "4:3", "3:4")
• output_format: Image format ("png", "webp", "jpg")
• guidance_scale: How closely to follow the prompt (1.0-10.0, default: 3.5)
• num_inference_steps: Quality vs speed tradeoff (1-50, default: 4)
• seed: Random seed for reproducible results (integer)
• num_outputs: Number of images to generate (1-4, default: 1)

{
  "input": {
    "prompt": "a majestic dragon flying over a medieval castle",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "guidance_scale": 4.0,
    "num_inference_steps": 8,
    "seed": 123456,
    "num_outputs": 1
  }
}

You can also use any top-level Replicate API parameters:

• webhook: URL to receive completion notifications
• webhook_events_filter: Which events to send to webhook
• stream: Enable streaming responses

The API now supports three request formats for POST requests:

1. Simple Format: {"prompt": "text"} (backward compatible)
2. Full Input Control: {"input": {...}} (new feature)
3. Full API Control: {"input": {...}, "webhook": "...", ...} (advanced)

// Simple format (backward compatible)
const response = await fetch('https://your-val-town-url.web.val.run/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_SERVICE_AUTH_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'a magical forest with glowing mushrooms'
  })
});

const result = await response.json();
console.log('Generated image:', result.imageUrl);

// Full API control with user token
const responseWithFullControl = await fetch('https://your-val-town-url.web.val.run/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Replicate-Token': 'r8_YOUR_REPLICATE_TOKEN'
  },
  body: JSON.stringify({
    input: {
      prompt: 'a magical forest with glowing mushrooms',
      aspect_ratio: '16:9',
      output_format: 'webp',
      guidance_scale: 4.0,
      num_inference_steps: 8,
      seed: 42
    },
    webhook: 'https://your-app.com/webhook'
  })
});

const resultWithFullControl = await responseWithFullControl.json();
console.log('Generated image:', resultWithFullControl.imageUrl);

import requests

# Simple format (backward compatible)
response = requests.post(
    'https://your-val-town-url.web.val.run/generate',
    headers={
        'Authorization': 'Bearer YOUR_SERVICE_AUTH_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'prompt': 'a serene mountain landscape'
    }
)

result = response.json()
print(f"Generated image: {result['imageUrl']}")

# Full API control with user token
response_with_full_control = requests.post(
    'https://your-val-town-url.web.val.run/generate',
    headers={
        'Content-Type': 'application/json',
        'X-Replicate-Token': 'r8_YOUR_REPLICATE_TOKEN'
    },
    json={
        'input': {
            'prompt': 'a serene mountain landscape at golden hour',
            'aspect_ratio': '16:9',
            'output_format': 'png',
            'guidance_scale': 3.5,
            'num_inference_steps': 6,
            'seed': 987654
        },
        'webhook': 'https://your-app.com/webhook'
    }
)

result_with_full_control = response_with_full_control.json()
print(f"Generated image: {result_with_full_control['imageUrl']}")

• Keep your Replicate API tokens secure
• Don't expose tokens in client-side code
• Use environment variables for token storage
• The service stores generated images temporarily in blob storage
• Images are accessible via direct URL without authentication

1. "Unauthorized access": Check your Authorization header or provide a valid replicate_token
2. "Missing 'prompt' parameter": Ensure you include a prompt in your request
3. "Replicate API error": Check your Replicate token validity and account limits
4. "Prediction timed out": The image generation took too long; try again with a simpler prompt

• Check the service logs for detailed error messages
• Verify your Replicate token at replicate.com
• Ensure your prompt is descriptive but not overly complex
• Check your Replicate account for usage limits and billing status

The updated image generation API now supports two authentication modes:

1. Service Authentication: Use the service's AUTH_TOKEN (existing behavior)
2. User Token Authentication: Provide your own Replicate token to bypass service auth (new feature)

• ✅ Added support for user-provided Replicate tokens via query parameter, header, or request body
• ✅ Authentication bypass when user provides their own token
• ✅ NEW: Full Replicate API body control for POST requests
• ✅ NEW: Support for all Flux model parameters (aspect_ratio, guidance_scale, etc.)
• ✅ NEW: Support for additional Replicate API features (webhooks, streaming, etc.)
• ✅ Maintained all existing functionality and backward compatibility
• ✅ Proper error handling for invalid tokens and requests
• ✅ Multiple token input methods for flexibility

1. X-Replicate-Token header (highest priority)
2. replicate_token in request body (POST only)
3. replicate_token query parameter (GET only)
4. Service's built-in token (fallback)

This implementation allows users to either use the service's authentication system or bring their own Replicate API tokens for direct access.