Übersicht

Die Ephemeral-API ist JSON über HTTPS. Ausführungen, Workflows, Dateien, Verbindungen und Modelle stellt die Engine bereit. Beim gehosteten Dienst stellt eine separate Organisations-API Organisationen, Mitglieder, Schlüssel und Abrechnung bereit.

Basis-URLs

Die Beispiele auf diesen Seiten verwenden $EPHEMERAL_URL für die Engine-Basis ohne das /v1.

Authentifizierung

Senden Sie bei jeder Engine-Anfrage einen API-Schlüssel der Organisation als Bearer-Token.

curl $EPHEMERAL_URL/v1/me \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY"

Gehostete Schlüssel beginnen mit eak_, selbst gehostete mit eph_. Ein Schlüssel gehört zu einer Organisation, Sie übergeben der Engine also nie eine Organisations-ID. Ob ein Schlüssel einen Endpunkt aufrufen darf, hängt von seiner Rolle ab; siehe Rollen und Schlüssel. Die Organisations-API lehnt API-Schlüssel für Verwaltungsaktionen ab und verlangt stattdessen einen angemeldeten Inhaber oder Admin; siehe Organisationen.

Anwendungen, die für eine Person handeln, etwa MCP-Clients, können sich stattdessen mit OAuth 2.1 anmelden (nur gehosteter Dienst): Authorization-Code-Flow mit PKCE, dynamische Client-Registrierung und die Scopes member und admin. Das Zugriffstoken (eoa_…, eine Stunde gültig) kommt in denselben Authorization: Bearer-Header und wirkt in der Organisation, die die Person gewählt hat. Discovery: Metadaten des Autorisierungsservers und Metadaten der geschützten Ressource. Siehe MCP.

{
  "organization_id": "org_5e2b8c91d4a7f03e6b1c9d2a8f4e7b10",
  "role": "member",
  "mode": "hosted",
  "compute_micros_per_second": 200,
  "default_max_cost_micros": 500000
}

Anfragen

• Senden Sie JSON mit Content-Type: application/json. Datei-Uploads sind die Ausnahme und verwenden Multipart-Formulardaten.
• Unbekannte Felder werden mit 400 abgelehnt, ein falsch geschriebenes Feld führt also zu einem Fehler.
• Zeitstempel sind RFC-3339-Strings in UTC.
• Geldfelder mit der Endung _micros sind ganzzahlige Millionstel eines US-Dollars. Felder mit der Endung _cents sind ganzzahlige Cent.

Fehler

Fehler liefern einen HTTP-Status und einen JSON-Body mit einer lesbaren Meldung in error.

{ "error": "timeout_seconds must be between 1 and 3600", "code": "invalid_request" }

Ratenbegrenzung

Anfragen an die Engine sind pro Minute begrenzt. Eine Anfrage mit Bearer-Token wird dieser Zugangsdaten-Kennung zugerechnet, mit 600 Anfragen pro Minute. Eine Anfrage ohne Token, etwa GET /v1/models, wird der Client-Adresse zugerechnet, mit 120 Anfragen pro Minute. Das Zeitfenster dauert eine Minute und beginnt mit jeder vollen Minute neu.

Jede Antwort der Engine, auch eine Fehlerantwort, zeigt Ihren Stand. RateLimit-Policy und RateLimit folgen dem IETF-Entwurf für RateLimit-Header (q ist das Kontingent, w das Zeitfenster in Sekunden, r die verbleibenden Anfragen und t die Sekunden bis zum Zurücksetzen). X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset liefern dieselben Werte unter den Namen, die viele Clients bereits lesen.

RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=598;t=41
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 41

Überschreiten Sie das Limit, antwortet die Engine mit 429, dem üblichen JSON-Fehler mit dem Code rate_limited und einem Retry-After-Header mit den zu wartenden Sekunden. Warten Sie so lange, statt sofort erneut zu senden. Das Verfolgen einer Ausführung mit GET /v1/runs/{id}/events zählt einmal pro Verbindung, nicht pro Ereignis.

Idempotentes Erstellen von Ausführungen

Netzwerkfehler können offenlassen, ob eine Ausführung erstellt wurde. Senden Sie mit POST /v1/runs einen Idempotency-Key-Header mit bis zu 200 Zeichen. Existiert in Ihrer Organisation bereits eine Ausführung mit diesem Schlüssel, gibt Ephemeral sie mit dem Status 200 zurück, statt eine weitere zu erstellen. Eine neue Ausführung liefert 202.

Paginierung

GET /v1/runs paginiert, wenn Sie limit (1 bis 100) oder cursor übergeben. Die Antwort lautet {"items": [...], "next_cursor": "..."}. Übergeben Sie next_cursor als cursor zurück, um die nächste Seite zu erhalten; ein leerer next_cursor bedeutet, dass Sie die letzte erreicht haben. Cursor sind opak und nur mit demselben status-Filter gültig. Ohne limit oder cursor ist die Antwort ein einfaches Array der 100 neuesten Ausführungen.

Versionen und Abkündigung

Die API ist im Pfad versioniert: Alle Endpunkte hier liegen unter /v1. Innerhalb einer Version kommen nur Ergänzungen hinzu: neue Endpunkte, neue optionale Anfragefelder, neue Antwortfelder und neue Ereignistypen. Bestehende Felder behalten Namen und Bedeutung; Clients sollten unbekannte Felder ignorieren.

Eine Änderung, die bestehende Clients brechen würde, erscheint als neue Version unter einem neuen Pfad. Die vorherige Version funktioniert nach der Veröffentlichung der neuen noch mindestens sechs Monate. Solange sie abgekündigt ist, tragen ihre Antworten einen Deprecation-Header und einen Sunset-Header mit dem Abschaltdatum, und die Inhaber der Organisationen werden per E-Mail informiert.

Referenz

Die Engine-API ist auch als OpenAPI-3.1-Beschreibung (https://app.ephemer.al/openapi.json) veröffentlicht, mit der Schlüsselrolle, die jede Operation benötigt. Die Schlüsselrollen member und admin stehen maschinenlesbar als scopes_supported in den Metadaten der geschützten Ressource.