Routing

OpenPixels provides flexible routing options that give you control over which providers handle your requests. This allows you to optimize for reliability, cost, or specific provider capabilities based on your application’s needs.

Routing options

When making requests to OpenPixels, you can specify routing preferences using the following options in the config object:

whitelist

The whitelist option allows you to specify an exclusive list of providers that OpenPixels should use for your request. When set, only the providers in this list will be considered.

• Type: Array<string>
• Optional: Yes
• Default: All available providers that support the requested model

When you set a whitelist, OpenPixels will only attempt to route your request to the specified providers. If none of the whitelisted providers can fulfill the request, it will fail rather than trying other providers.

ordering

The ordering option lets you express a soft preference for where your requests should be fulfilled. This is useful when you have credits with specific providers or prefer certain providers for specific types of tasks.

• Type: Array<string>
• Optional: Yes
• Default: Model’s default provider ordering

Unlike the whitelist, ordering is a soft preference. If the providers in the ordering are unhealthy, OpenPixels might fall back to a provider that is not in the ordering in order to fulfill the request. It may also skip providers in the ordering if it determines that they are unhealthy.

strategy

The strategy option determines the general approach to selecting providers when no explicit ordering is provided, or when the providers in the ordering are unhealthy.

• Type: String (“best” or “random”)
• Optional: Yes
• Default: “best”

Options:

• “best”: OpenPixels will choose providers based on their reliability and performance for the specific model. This is the recommended option for most use cases.
• “random”: Providers will be selected randomly from those that support the requested model. Not recommended.

Examples

Here are the most common routing configurations:

Example 1: Default Routing (Best Provider)

The simplest approach is to let OpenPixels choose the best provider for you:

// Let OpenPixels automatically choose the best provider
client.run({
  model: 'flux-dev',
  prompt: 'a beautiful sunset over the ocean'
  // No routing options specified - will use defaults (strategy: "best")
});

In this example, OpenPixels will automatically select the best-performing provider for the requested model based on current health metrics and performance history.

Example 2: Prioritizing a Specific Provider (Where You Have Credits)

If you have credits on a specific provider like fal.ai and want to prioritize it:

// Try fal.ai first since you have credits there. If it's unhealthy, we'll fall back to the implicit strategy: "best"
client.run({
  model: 'flux-dev',
  prompt: 'a beautiful sunset over the ocean',
  config: {
    routing: {
      ordering: ['fal']
    }
  }
});

In this example, OpenPixels will first attempt to use fal.ai. If that fails or if fal.ai is unhealthy, it will fall back to the best healthy provider.

Example 3: Restricting to a Single Provider (Cost Control)

If you want to ensure your requests only ever go to specific providers, for example, because fal.ai is too expensive:

// Only use runware.ai to control costs
client.run({
  model: 'flux-dev',
  prompt: 'a beautiful sunset over the ocean',
  config: {
    routing: {
      whitelist: ['runware']
    }
  }
});

In this example, OpenPixels will only attempt to use runware.ai. If runware.ai fails, the request will fail rather than trying other providers like fal.ai.

Reference

Routing Configuration