> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDream Images Generation API интеграция
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
В этой статье будет представлено руководство по интеграции SeeDream Images Generation API, который позволяет генерировать изображения от SeeDream, вводя пользовательские параметры.
## Процесс подачи заявки
Чтобы использовать SeeDream Images Generation API, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications), чтобы получить ваш API Token и сохранить его на всякий случай.
Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу.
**Один API Token позволяет вызывать все сервисы платформы, не нужно подавать отдельные заявки на каждый сервис.** При первой подаче заявки предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin).
> 📘 Полная документация: [SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)
## Основное использование
Сначала ознакомьтесь с основным способом использования, который заключается в вводе подсказки `prompt`, действия `action`, размера изображения `size`, чтобы получить обработанный результат. Сначала необходимо просто передать поле `action`, значение которого равно `generate`, затем нам также нужно ввести подсказку, конкретное содержание выглядит следующим образом:
Как видно, мы настроили заголовки запроса, включая:
* `accept`: формат ответа, который вы хотите получить, здесь указано `application/json`, то есть формат JSON.
* `authorization`: ключ для вызова API, после запроса его можно выбрать из выпадающего списка.
Также настроено тело запроса, включая:
* `prompt`: подсказка.
* `model`: модель генерации, по умолчанию `doubao-seedream-5-0-260128` (SeeDream 5.0 Lite, последняя версия). Поддерживаются `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828`, `doubao-seedream-3-0-t2i-250415`, `doubao-seededit-3-0-i2i-250628`. Из них `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) является флагманской моделью для одиночного изображения, генерирует только одно изображение, **не поддерживает групповые изображения (`sequential_image_generation`), потоковую передачу (`stream`) и сетевой поиск (`tools`)**. **`model` должен передаваться в полном виде (например, `doubao-seedream-5-0-260128`), передача сокращений, таких как `doubao-seedream-5.0-lite`, приведет к ошибке 400.**
* `image`: информация о входном изображении, поддерживает URL или кодировку Base64. Из них `doubao-seedream-5-0-pro-260628` поддерживает ввод одного или нескольких изображений (много изображений 2-10 штук, начиная со второго изображения, будет взиматься плата за каждое), `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` поддерживают ввод одного или нескольких изображений, `doubao-seededit-3-0-i2i-250628` поддерживает только ввод одного изображения, `doubao-seedream-3-0-t2i-250415` не поддерживает этот параметр.
* `size`: указывает информацию о размере генерируемого изображения, поддерживает следующие два способа, которые нельзя комбинировать. Способ 1 | Указывает разрешение генерируемого изображения и описывает соотношение сторон изображения на естественном языке в `prompt`. **Поддерживаемые предустановки различаются для каждой модели**: `doubao-seedream-5-0-pro-260628` поддерживает `1K`/`2K`; `doubao-seedream-5-0-260128` поддерживает `2K`/`3K`/`4K`; `doubao-seedream-4-5-251128` поддерживает только `2K`/`4K`; `doubao-seedream-4-0-250828` поддерживает `1K`/`2K`/`4K`; `doubao-seedream-3-0-t2i-250415` и `doubao-seededit-3-0-i2i-250628` **не поддерживают предустановки**, принимают только способ 2. Способ 2 | Указывает значения пикселей ширины и высоты генерируемого изображения: по умолчанию `2048x2048`, общий диапазон пикселей и соотношение сторон различаются в зависимости от модели (например, для 5.0 Pro общий диапазон пикселей \[921600, 4194304], для 5.0 Lite / 4.5 нижний предел общего пикселя 3,686,400, для 4.0 нижний предел 921,600, для 3.0-t2i / seededit-3.0-i2i диапазон \[512x512, 2048x2048]).
* `seed`: случайное число, используемое для управления случайностью генерируемого контента. Диапазон значений от \[-1, 2147483647]. **Только `doubao-seedream-3-0-t2i-250415` поддерживает этот параметр**.
* `sequential_image_generation`: групповые изображения: на основе введенного вами контента генерируется набор связанных изображений. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` поддерживают этот параметр, по умолчанию `disabled`.
* `stream`: управляет тем, включен ли режим потокового вывода. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` поддерживают этот параметр, по умолчанию `false`.
* `guidance_scale`: степень соответствия результата модели и подсказки, чем больше значение, тем сильнее связь. Диапазон значений \[1, 10]. `doubao-seedream-3-0-t2i-250415` имеет значение по умолчанию 2.5, `doubao-seededit-3-0-i2i-250628` имеет значение по умолчанию 5.5, другие модели не поддерживают.
* `response_format`: указывает формат возвращаемого изображения. По умолчанию `url`, также поддерживает `b64_json`.
* `watermark`: добавлять ли водяной знак на сгенерированное изображение. По умолчанию `true`.
* `output_format`: указывает формат файла генерируемого изображения, поддерживает `jpeg` (по умолчанию) и `png`. Поддерживается только `doubao-seedream-5-0-pro-260628` и `doubao-seedream-5-0-260128`.
* `tools`: настраивает инструменты, которые модель должна вызывать, в настоящее время поддерживает `web_search` (сетевой поиск). Поддерживается только `doubao-seedream-5-0-260128`.
* `callback_url`: URL, на который нужно отправить результаты.
* `async`: обрабатывать ли в асинхронном режиме. Установите в `true`, чтобы интерфейс немедленно вернул `task_id`, без необходимости предоставлять `callback_url`, затем с помощью `/seedream/tasks` опрашивайте для получения результатов.
После выбора вы также можете увидеть сгенерированный код справа, как показано на изображении:
Нажмите кнопку «Попробовать», чтобы протестировать, как показано на изображении выше, и мы получили следующий результат:
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "Фотореалистичный студийный снимок парфюмерной бутылки из матового стекла на мокром черном сланце, одно основное освещение софтбокса, капли воды, темный мрачный фон, 85 мм макро.",
"size": "2048x2048",
"image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
}
]
}
```
Возвращаемый результат содержит несколько полей, описание которых следующее:
* `success` — состояние задачи по генерации видео в данный момент.
* `task_id` — ID задачи по генерации видео в данный момент.
* `trace_id` — ID отслеживания задачи по генерации видео в данный момент.
* `data` — список результатов задачи по генерации изображения в данный момент.
* `image_url` — ссылка на задачу по генерации изображения в данный момент.
* `prompt` — подсказка.
* `size` — пиксели сгенерированного изображения.
Можно увидеть, что мы получили удовлетворительную информацию о изображении, нам нужно просто получить сгенерированное изображение SeeDream по ссылке `image_url` в результате.
Кроме того, если вы хотите сгенерировать соответствующий код для интеграции, вы можете просто скопировать его, например, код CURL выглядит следующим образом:
```shell theme={null}
curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "doubao-seedream-5-0-260128",
"prompt": "Фотореалистичный студийный снимок парфюмерной бутылки из матового стекла на мокром черном сланце, одно основное освещение софтбокса, капли воды, темный мрачный фон, 85 мм макро."
}'
```
## Редактирование изображения
Если вы хотите отредактировать определенное изображение, сначала параметр `image` должен содержать ссылку на изображение, которое нужно редактировать.
* model: модель, используемая для редактирования изображения, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` поддерживают ввод одного или нескольких изображений, `doubao-seededit-3-0-i2i-250628` поддерживает только одно изображение.
* image: загружаемое изображение для редактирования, одно или несколько.
Пример заполнения:
Соответствующий код:
```python theme={null}
import requests
url = "https://api.acedata.cloud/flux/images"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedream-4-0-250828",
"prompt": "Сохраните позу модели и форму струящегося жидкого наряда без изменений. Измените материал одежды с серебряного металла на полностью прозрачную воду (или стекло). Через поток жидкости видны детали кожи модели. Эффект света и тени смещается от отражения к преломлению.",
"image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
"size": "2K",
"watermark": False
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Нажав "Запустить", можно увидеть, что сразу будет получен результат, как показано ниже:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Сохраните позу модели и форму струящегося жидкого наряда без изменений. Измените материал одежды с серебряного металла на полностью прозрачную воду (или стекло). Через поток жидкости видны детали кожи модели. Эффект света и тени смещается от отражения к преломлению.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Можно увидеть, что сгенерированный эффект — это результат редактирования оригинального изображения, результат аналогичен вышеупомянутому.
## Асинхронный обратный вызов
Поскольку время генерации изображений SeeDream Images Generation API относительно долгое, примерно 1-2 минуты, если API долго не отвечает, HTTP-запрос будет постоянно поддерживать соединение, что приведет к дополнительному потреблению системных ресурсов, поэтому этот API также поддерживает асинхронные обратные вызовы.
Общий процесс: когда клиент инициирует запрос, дополнительно указывается поле `callback_url`. После того как клиент инициирует API-запрос, API немедленно возвращает результат, содержащий информацию о поле `task_id`, представляющем текущий ID задачи. Когда задача завершена, результат сгенерированного изображения будет отправлен на указанный клиентом `callback_url` в формате POST JSON, который также включает поле `task_id`, так что результат задачи можно связать по ID.
Если у вас нет общедоступного адреса для обратного вызова, вы также можете не указывать `callback_url`, а установить поле `async` в `true` в запросе. В этом случае интерфейс также немедленно вернет `task_id`, но не будет отправлять результат, вам нужно будет использовать этот `task_id` для вызова интерфейса `/seedream/tasks` для опроса состояния задачи, чтобы получить окончательный результат.
Давайте рассмотрим пример, чтобы понять, как это работает.
Нажав "Запустить", можно увидеть, что сразу будет получен результат, как показано ниже:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
Содержимое следующее:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Сохраните позу модели и форму струящегося жидкого наряда без изменений. Измените материал одежды с серебряного металла на полностью прозрачную воду (или стекло). Через поток жидкости видны детали кожи модели. Эффект света и тени смещается от отражения к преломлению.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Можно увидеть, что в результате есть поле `task_id`, остальные поля аналогичны вышеупомянутым, с помощью этого поля можно реализовать связь задач.
## Обработка ошибок
При вызове API, если возникла ошибка, API вернет соответствующий код ошибки и информацию. Например:
* `400 token_mismatched`: Неверный запрос, возможно, из-за отсутствия или недействительных параметров.
* `400 api_not_implemented`: Неверный запрос, возможно, из-за отсутствия или недействительных параметров.
* `401 invalid_token`: Неавторизовано, недействительный или отсутствующий токен авторизации.
* `429 too_many_requests`: Слишком много запросов, вы превысили лимит частоты.
* `500 api_error`: Внутренняя ошибка сервера, что-то пошло не так на сервере.
### Пример ответа об ошибке
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Заключение
С помощью этого документа вы уже узнали, как использовать API генерации изображений SeeDream, чтобы создавать изображения на основе вводимых подсказок. Надеемся, что этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.