Upstreams are the real provider endpoints behind platform models. Create an upstream, add one or more API keys, set protocols and timeouts, sync its remote models, and manage route bindings.

Where to find it#

Open the admin console and select Upstreams. The toolbar has search, Status and Compatibility filters, sorting, Sync, and bulk actions. The Automatic circuit breaker switch at the top right controls whether circuit state is shown and used.

Create an upstream#

1. Click Create.
2. Enter Name and Base URL, for example https://api.example.com/v1.
3. Paste API keys under API keys (multi-key rotation), one key per line.
4. Choose Compatibility and Status.
5. Expand Default protocols, Timeouts, Circuit breaker, and Request headers to set optional values.
6. Click Create.

Name, base URL, and at least one API key are required on create. Keys are stored as a rotation list with the round_robin strategy, so requests spread across the configured keys.

Edit an upstream and rotate keys#

Open Edit from the row menu. The form loads the current values, but plaintext keys are never shown.

• To add keys, paste new keys under Add API keys. They are appended to the rotation list.
• Each existing key shows a masked value and a delete action. Deleting marks the key for removal and takes effect after saving.
• At least one active key must remain. If you delete the last one, add a new key before saving, or the save is rejected with Keep at least one API key, or enter new API keys before saving.

Set per-kind default protocols#

Expand Default protocols to set the protocol used for each kind when a route does not specify one. Kinds are Chat, Audio, Image generation, Image editing, Video generation, and Video extension. Each kind lists only the protocols that apply to it. Leave a kind on System default to let the backend infer the protocol from the compatibility type.

Configure timeouts#

Blank values use the system default. The list column shows the configured values in seconds.

Configure the circuit breaker#

Circuit breaker settings take effect only when Automatic circuit breaker is enabled.

A circuit-open upstream stops receiving new requests until the duration ends or you reset it. The row shows an Expected recovery time in the tooltip.

Add request headers#

Expand Request headers and edit the JSON object. Quick fill adds common presets without overwriting existing headers:

If a preset uses a name that already exists with another value, the fill is rejected with a conflict message. Fix the JSON first if the editor cannot parse it.

Sync remote models#

1. Open Sync from the row menu, or click Sync in the model management dialog.
2. Wait for the remote catalog to load. The header summarizes the planned changes: Add, Update, Restore, Deactivate, Unchanged, and Preserve.
3. Review the remote models, select the ones to bind, and edit each Platform model name.
4. Optionally choose Add to groups to place imported models into permission groups.
5. Click Apply sync.

If the sync would deactivate models that the upstream no longer returns, a confirmation explains the impact. Deactivation only changes the upstream catalog status; platform models and route bindings are kept, and models are restored automatically if the upstream returns them later.

After binding, the summary reports imported, failed, created platform models, created routes, and reused routes. Use Reload to fetch the remote catalog again.

Manage route bindings#

Open Manage models from the row menu. The dialog lists the bindings for this upstream.

1. Search by upstream model, platform model, protocol, or status.
2. Filter by Route status, Upstream status, and Protocol, and sort as needed.
3. Toggle a route with the switch, edit the Platform model name, or change Protocol and Kind.
4. Use the bulk controls to apply route status, protocol, or kind to selected rows.
5. Click Save.

To create a binding manually, click Create, enter the Upstream model name and Platform model name, choose Protocol, Kind, and Status, then Save. An active route requires a platform model name; to unbind, disable the route first. Deleting bindings keeps the upstream model catalog, so you can rebind by syncing later.

Open or reset a circuit#

When Automatic circuit breaker is enabled, the row menu shows Open circuit or Reset circuit depending on the current state.

• Open circuit now stops new requests until the duration ends or you reset it.
• Reset circuit resumes requests immediately.

Both actions ask for confirmation. Use manual open during provider maintenance, credential problems, or network issues, and reset only after confirming recovery.

Bulk status and delete#

Select rows with the checkboxes.

• To change status, pick Active or Disabled in the bulk status control and click Apply, then confirm.
• To delete, click Delete, then confirm. Deleting an upstream removes its route bindings but keeps the model catalog.

Bulk actions report how many items succeeded and how many failed.

Troubleshooting#

Related#

• Models
• Permission groups
• Billing
• Logs