Solution API d’édition
Les points d’accès d’édition prennent au moins deux entrées : l’image et l’instruction. C’est sur l’image — URL publique, téléversement validé ou data URI intégrée — que la plupart des intégrations bloquent.
L’enjeu
L’invite est la moitié facile. L’autre est un fichier sur le téléphone de vos utilisateurs, qui doit atteindre le modèle sans exposer un bucket privé et respecter des limites vérifiées avant même l’existence de la tâche.
01
Un champ image déclaré accepte une URL HTTPS publique, une URI de fichier spicy:// validée, ou une data URI intégrée. En intégré : 1 Mio décodé et 8 388 608 pixels par image, dans un corps de 2 Mio. Au-delà, il faut un ticket de téléversement.
02
Un lien signé peut pointer vers un bucket privé si nos serveurs téléchargent le fichier sans cookies ni connexion séparée. Gardez-le valide pendant le traitement. Les IP privées, le loopback et les identifiants user:password dans l’URL sont refusés.
03
Le nom d’appel public se termine par /edit, le schéma exige généralement image_url ou image_urls, et certains points d’accès ajoutent mask_url ou strength. Une valeur model de type text-to-image dans un flux d’édition échoue à la validation au lieu de se dégrader.
La méthode
Pour les fichiers utilisateurs, demandez un ticket, envoyez en PUT exactement le nombre d’octets déclaré avec tous les en-têtes renvoyés, validez, puis passez l’URI spicy:// dans le champ image du modèle. La référence appartient alors à votre compte, est vérifiée une fois et se réutilise sans nouveau téléversement.
Ticket, PUT, validation, création. Un média déjà public saute les trois premières étapes.
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"]
}
}Contrat
| Champ ou en-tête | Valeur ou limite |
|---|---|
| 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 |
Balayez horizontalement pour voir toutes les colonnes.
Intégration
Pertinence
Vérifications
La validation compare le nombre d’octets et le type de média au ticket, contrôle la signature de l’image et calcule un SHA-256. Ce n’est qu’ensuite que le fichier devient référençable.
Les data URI sont stockées comme fichiers liés au compte. L’entrée normalisée renvoyée par recordInfo contient des URI de fichiers, jamais les octets Base64 d’origine.
Le matériel téléversé est conservé un jour, les résultats générés 14 jours. Les deux durées sont publiées, pas négociées par compte.
Avant la mise en production
Questions fréquentes
Modèles
Chaque lien ouvre la page de la famille de modèles concernée : entrées, limites, politique de contenu et prix actuel à l’unité.
Et après
Envoyez une image que vous possédez et une instruction. Comment la référence entre, quelles limites de pixels s’appliquent et ce qui est facturé.
