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"
}

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

This service uses the black-forest-labs/flux-schnell model on Replicate, which:

• Generates high-quality images
• Supports various artistic styles
• Outputs PNG format images
• Typically takes 2-10 seconds to generate

// Using service authentication
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);

// Using your own Replicate token
const responseWithUserToken = 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({
    prompt: 'a magical forest with glowing mushrooms'
  })
});

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

import requests

# Using service authentication
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']}")

# Using your own Replicate token
response_with_user_token = requests.post(
    'https://your-val-town-url.web.val.run/generate',
    headers={
        'Content-Type': 'application/json',
        'X-Replicate-Token': 'r8_YOUR_REPLICATE_TOKEN'
    },
    json={
        'prompt': 'a serene mountain landscape'
    }
)

result_with_user_token = response_with_user_token.json()
print(f"Generated image: {result_with_user_token['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
• ✅ Maintained all existing functionality and behavior
• ✅ Proper error handling for invalid tokens
• ✅ 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.