Решение: редактирование
Эндпоинты редактирования принимают минимум два входа: изображение и инструкцию. Именно на изображении — публичная ссылка, подтверждённая загрузка или встроенный data URI — застревает большинство интеграций.
Задача
Текст запроса — простая половина. Вторая — файл в телефоне вашего пользователя, который должен дойти до модели, не раскрывая приватное хранилище, и уложиться в пределы, проверяемые ещё до появления задачи.
01
Объявленное поле изображения принимает публичный HTTPS-адрес, подтверждённый файловый URI spicy:// или встроенный data URI. Встроенное: 1 МиБ после декодирования и 8 388 608 пикселей на изображение, при теле запроса до 2 МиБ. Всё, что больше, идёт через талон загрузки.
02
Подписанная ссылка может вести к закрытому бакету, если наши серверы скачивают файл без cookies и отдельного входа. Она должна действовать во время обработки. Частные IP, loopback и данные user:password в URL запрещены.
03
Публичное имя вызова оканчивается на /edit, схема обычно требует image_url или image_urls, а некоторые эндпоинты добавляют mask_url или strength. Значение model от text-to-image в потоке редактирования не деградирует мягко, а падает на проверке.
Подход
Для пользовательских файлов запросите талон, отправьте PUT ровно указанное число байтов со всеми возвращёнными заголовками, подтвердите файл и передайте полученный URI spicy:// в поле изображения модели. Дальше ссылка принадлежит вашему аккаунту, проверяется один раз и переиспользуется без повторной загрузки.
Талон, PUT, подтверждение, создание. Уже публично доступная медиа-ссылка пропускает первые три шага.
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"]
}
}Контракт
| Поле или заголовок | Значение или предел |
|---|---|
| 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 |
Проведите по горизонтали, чтобы увидеть все столбцы.
Интеграция
Применимость
Проверки
Подтверждение сверяет число байтов и тип содержимого с талоном, проверяет сигнатуру изображения и считает SHA-256. Только после этого на файл можно ссылаться.
Data URI сохраняются как привязанные к аккаунту файлы. Нормализованный ввод, который отдаёт recordInfo, содержит файловые URI, а не исходные байты Base64.
Загруженный материал хранится один день, сгенерированные результаты — 14 дней. Оба срока опубликованы и не обсуждаются отдельно по аккаунтам.
Перед запуском
Частые вопросы
Модели
Каждая ссылка ведёт на страницу семейства моделей: входные данные, ограничения, контентная политика и текущая цена за единицу.
Дальше
Отправьте имеющееся изображение и инструкцию. Как ссылка попадает внутрь, какие пределы по пикселям и за что берётся плата.
Другие руководства
