Provider Parameters

The provider_params field lets you pass provider-specific parameters that aren’t part of Eden AI’s unified schema. This gives you access to advanced or niche options offered by individual providers without breaking the standard request format.

How It Works

Add a provider_params object to any Universal AI request. Its contents are forwarded to the provider alongside the standard input fields. On most subfeatures any parameter is forwarded as-is; video generation and the web subfeatures accept only the parameters on an allowlist (see Parameter Validation and Allowlisting).

{
  "model": "{feature}/{subfeature}/{provider}[/{model}]",
  "input": {
    // Standard unified parameters
  },
  "provider_params": {
    // Provider-specific parameters, in the provider's own request format
  }
}

Basic Example

import requests

url = "https://api.edenai.run/v3/universal-ai"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "image/generation/openai/gpt-image-2",
    "input": {
        "text": "A futuristic city at sunset, cyberpunk style"
    },
    "provider_params": {
        "quality": "hd",
        "style": "vivid"
    }
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result)

const url = 'https://api.edenai.run/v3/universal-ai';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

const payload = {
  model: 'image/generation/openai/gpt-image-2',
  input: {
    text: 'A futuristic city at sunset, cyberpunk style'
  },
  provider_params: {
    quality: 'hd',
    style: 'vivid'
  }
};

const response = await fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
});

const result = await response.json();
console.log(result);

curl -X POST https://api.edenai.run/v3/universal-ai \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image/generation/openai/gpt-image-2",
    "input": {
      "text": "A futuristic city at sunset, cyberpunk style"
    },
    "provider_params": {
      "quality": "hd",
      "style": "vivid"
    }
  }'

Common Use Cases

Image Generation: Style and Quality

Control output style and quality for image generation:

import requests
import base64
from PIL import Image
from io import BytesIO

url = "https://api.edenai.run/v3/universal-ai"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "image/generation/openai/gpt-image-2",
    "input": {
        "num_images": 1,
        "text": "A watercolor painting of a mountain landscape",
        "resolution": "1792x1024"
    },
    "provider_params": {
        "style": "vivid",
        "quality": "hd" #Default is standard
    }
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()

img_url = data["output"]["items"][0]["image_resource_url"]
img_response = requests.get(img_url)
img = Image.open(BytesIO(img_response.content))
img.save('image.png')
img.show()

Text to Speech: Voice Settings

Pass provider-specific voice parameters:

import requests

url = "https://api.edenai.run/v3/universal-ai"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "audio/tts/google/gemini-2.5-flash-tts",
    "input": {
      "voice": "achernar",
      "text": "Bonjour, j'adore la tourte.",
      "audio_format": "mp3"
    },
    "provider_params": {
      "language_code": "fr-FR",
      "prompt": "say this while crying"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Parameter Validation and Allowlisting

For most subfeatures, Eden AI forwards provider_params directly to the provider without validation. Invalid parameters may cause provider errors. These subfeatures accept only the parameters on a per-provider allowlist, which each page lists under Provider Parameters:

Video generation: video/generation_async
Web: web/search, web/scraping, web/map, web/crawl_async, web/batch_scrape_async, web/structured_extraction_async, and web/research_async

Any other parameter is rejected with a 400 Bad Request error naming the parameters that were refused. The check covers every provider the request can reach: with fallbacks, each parameter must be allowed for the provider in model and for every fallback provider, or the whole request is rejected.

Discovering Allowed Parameters

To read an allowlist from your code, query the subfeature detail endpoint:

curl https://api.edenai.run/v3/info/video/generation_async \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.edenai.run/v3/info/video/generation_async",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

for provider, paths in response.json()["provider_params"].items():
    print(provider, paths)

The response includes a provider_params object mapping each provider to its accepted parameter paths. Abridged to three of the providers:

{
  "provider_params": {
    "amazon": [
      "texttovideoparams.images.format",
      "texttovideoparams.images.source.bytes",
      "texttovideoparams.text",
      "videogenerationconfig.dimension",
      "videogenerationconfig.fps",
      "videogenerationconfig.seed"
    ],
    "google": [
      "aspectratio",
      "compressionquality",
      "enhanceprompt",
      "generateaudio",
      "negativeprompt",
      "persongeneration",
      "resizemode",
      "seed",
      "video.uri"
    ],
    "openai": ["input_reference", "prompt"]
  }
}

Each entry is a path in the provider’s own request format, lowercased, with nested keys joined by dots. Send the parameter as a nested object, in the casing the provider documents. videogenerationconfig.seed for Amazon means:

{
  "provider_params": {
    "videoGenerationConfig": {
      "seed": 7
    }
  }
}

Likewise, Google’s aspectratio is sent as aspectRatio. The allowlist check ignores case, so a lowercased aspectratio passes it, but the provider then receives a key it does not recognize. An empty list means the provider accepts no provider_params, and null means the subfeature does not restrict them. To list every subfeature that restricts provider_params, call GET /v3/info?include=schemas (see List Expert Models) and keep the subfeatures whose provider_params is not null. You can also check the documentation_url field returned for each model in GET /v3/info to view the provider’s official documentation.

Important Notes

Available parameters vary by provider and feature. Refer to the provider’s own documentation for what each one does.
provider_params are sent to every provider the request reaches, including fallbacks. On subfeatures without an allowlist, a parameter one fallback provider does not support can make that attempt fail.

Next Steps

Bring Your Own Key

Use your own provider API keys for full control over costs and limits

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

How It Works

Basic Example

Common Use Cases

Image Generation: Style and Quality

Text to Speech: Voice Settings

Parameter Validation and Allowlisting

Discovering Allowed Parameters

Important Notes

Next Steps

Bring Your Own Key

​How It Works

​Basic Example

​Common Use Cases

​Image Generation: Style and Quality

​Text to Speech: Voice Settings

​Parameter Validation and Allowlisting

​Discovering Allowed Parameters

​Important Notes

​Next Steps

Bring Your Own Key

How It Works

Basic Example

Common Use Cases

Image Generation: Style and Quality

Text to Speech: Voice Settings

Parameter Validation and Allowlisting

Discovering Allowed Parameters

Important Notes

Next Steps