Bearbeitungs-API-Lösung
Bearbeitungs-Endpunkte nehmen mindestens zwei Eingaben: das Bild und die Anweisung. Genau am Bild scheitern die meisten Integrationen – als öffentliche URL, als bestätigter Upload oder als eingebettete Data-URI.
Die Herausforderung
Der Prompt ist die leichte Hälfte. Die andere ist eine Datei auf dem Telefon Ihrer Nutzer, die das Modell erreichen muss, ohne einen privaten Bucket offenzulegen, und die Grenzen einhalten muss, die vor der Auftragserstellung geprüft werden.
01
Ein deklariertes Bildfeld akzeptiert eine öffentliche HTTPS-URL, eine bestätigte spicy://-Datei-URI oder eine eingebettete Data-URI. Eingebettet gilt: 1 MiB dekodiert und 8.388.608 Pixel je Bild, insgesamt 2 MiB Anfragekörper. Alles darüber braucht ein Upload-Ticket.
02
Ein signierter Link kann auf einen privaten Bucket zeigen, wenn unsere Server die Datei ohne Cookies oder weitere Anmeldung laden können. Er muss während der Verarbeitung gültig bleiben. Private IPs, Loopback und user:password-URL-Zugangsdaten werden abgewiesen.
03
Der öffentliche Aufrufname endet auf /edit, das Schema verlangt meist image_url oder image_urls, manche Endpunkte ergänzen mask_url oder strength. Ein text-to-image-Wert im Bearbeitungsablauf scheitert an der Prüfung, statt sich anzupassen.
Der Ansatz
Fordern Sie für Nutzerdateien ein Upload-Ticket an, senden Sie per PUT exakt die angegebene Byte-Zahl mit allen zurückgegebenen Headern, bestätigen Sie die Datei und übergeben Sie die spicy://-URI im Bildfeld des Modells. Die Referenz gehört dann zu Ihrem Konto, wird einmal geprüft und ist ohne erneuten Upload wiederverwendbar.
Ticket, PUT, Bestätigung, Erstellung. Öffentlich erreichbare Medien überspringen die ersten drei Schritte.
Ticket → PUT → commit → create
POST /api/v1/common/upload-url
{ "contentType": "image/png", "bytes": 482113 }
→ { "fileId": "fil_01k3…", "uploadUrl": "https://…", "method": "PUT", "headers": { … } }
PUT <uploadUrl> # exactly 482113 bytes, every returned header replayed
POST /api/v1/files/fil_01k3…/commit
→ { "status": "ready", "uri": "spicy://f/fil_01k3…", "sha256": "…" }POST /api/v1/jobs/createTask
{
"model": "<publisher>/<model>/edit",
"input": {
"prompt": "Replace the background with an overcast beach at dusk",
"image_urls": ["spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"]
}
}Vertrag
| Feld oder Header | Wert oder Grenze |
|---|---|
| POST /api/v1/common/upload-url | JPEG · PNG · WebP · GIF ≤ 10 MiB |
| POST /api/v1/files/{fileId}/commit | returns spicy://f/fil_… |
| inline data URI | ≤ 1 MiB decoded · ≤ 8192 px per side |
| request body | ≤ 2 MiB · ≤ 16 images |
Horizontal wischen, um alle Spalten zu sehen.
Integration
Passung
Belege
Die Bestätigung vergleicht Byte-Zahl und Medientyp mit dem Ticket, prüft die Bildsignatur und berechnet einen SHA-256. Erst danach ist die Datei referenzierbar.
Data-URIs werden als kontogebundene Dateien gespeichert. Die von recordInfo zurückgegebene normalisierte Eingabe enthält Datei-URIs, nie die ursprünglichen Base64-Bytes.
Hochgeladenes Material wird einen Tag vorgehalten, erzeugte Ergebnisse 14 Tage. Beide Fristen sind veröffentlicht und nicht kontoabhängig verhandelbar.
Vor dem Start
Häufige Fragen
Modelle
Jeder Link führt auf die Seite der jeweiligen Modellfamilie: Eingaben, Grenzen, Inhaltsrichtlinie und der aktuelle Preis je Einheit.
Weiter
Schicken Sie ein vorhandenes Bild plus Anweisung. Wie Referenzen hineinkommen, welche Pixelgrenzen gelten und wofür Bearbeitung abgerechnet wird.
