> ## 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.
# Instrucciones de integración de SeeDream Images Generation API
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
Este artículo presentará unas instrucciones de integración de SeeDream Images Generation API, que permite generar imágenes oficiales de SeeDream introduciendo parámetros personalizados.
## Proceso de solicitud
Para utilizar SeeDream Images Generation API, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo para usarlo más adelante.
Si aún no ha iniciado sesión o no se ha registrado, se le redirigirá automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual.
**Un API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye saldo gratuito para una experiencia sin costo; cuando el saldo sea insuficiente, puede recargar el saldo general en la [consola](https://platform.acedata.cloud/console/coin).
> 📘 Documentación completa: [SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)
## Uso básico
Primero, veamos el uso básico: introduciendo el texto de indicación `prompt`, la acción de generación `action` y el tamaño de imagen `size`, puede obtener el resultado procesado. Primero debe pasar simplemente un campo `action` con el valor `generate`, y después también debe introducir el texto de indicación; el contenido específico es el siguiente:
Aquí podemos ver que configuramos los Request Headers, incluidos:
* `accept`: el formato de resultado de respuesta que desea recibir; aquí se rellena como `application/json`, es decir, formato JSON.
* `authorization`: la clave para llamar a la API; después de solicitarla, puede seleccionarla directamente en el menú desplegable.
También se configuró el Request Body, incluido:
* `prompt`: texto de indicación.
* `model`: modelo de generación, el predeterminado es `doubao-seedream-5-0-lite-260128` (SeeDream 5.0 Lite, el más reciente). Admite `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-lite-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828`. Entre ellos, `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) es un modelo insignia de imagen única, que solo genera una imagen, **no admite grupos de imágenes (`sequential_image_generation`), transmisión en flujo (`stream`) ni búsqueda web (`tools`)**. **`model` debe recibir la cadena completa del modelo (como `doubao-seedream-5-0-lite-260128`); pasar abreviaturas como `doubao-seedream-5.0-lite` devolverá 400.**
* `image`: información de la imagen de entrada; admite URL o codificación Base64. `doubao-seedream-5-0-pro-260628` admite entrada de una o varias imágenes (hasta 10), y `doubao-seedream-5-0-lite-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` admiten entrada de una o varias imágenes.
* `size`: especifica la información de tamaño de la imagen generada; admite las siguientes dos formas, que no se pueden mezclar. Forma 1 | Especificar la resolución de la imagen generada y describir la relación de aspecto de la imagen con lenguaje natural en el prompt. **Los preajustes admitidos por cada modelo son diferentes**: `doubao-seedream-5-0-pro-260628` admite `1K`/`1.5K`/`2K`; `doubao-seedream-5-0-lite-260128` admite `2K`/`3K`/`4K`; `doubao-seedream-4-5-251128` solo admite `2K`/`4K`; `doubao-seedream-4-0-250828` admite `1K`/`2K`/`4K`. Forma 2 | Especificar los valores de píxeles de ancho y alto de la imagen generada: el valor predeterminado es `2048x2048`; el rango de valores del total de píxeles y de la relación de aspecto varía según el modelo (por ejemplo, el rango total de píxeles de 5.0 Pro es \[921600, 4624220], el límite inferior total de píxeles de 5.0 Lite / 4.5 es 3,686,400 y el límite inferior de 4.0 es 921,600).
* `sequential_image_generation`: grupo de imágenes: un conjunto de imágenes con contenido relacionado generado según el contenido introducido. `doubao-seedream-5-0-lite-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` admiten este parámetro; el valor predeterminado es `disabled`.
* `stream`: controla si se activa el modo de salida en flujo. `doubao-seedream-5-0-lite-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` admiten este parámetro; el valor predeterminado es `false`.
* `response_format`: especifica el formato de retorno de la imagen generada. El valor predeterminado es `url`, y también admite `b64_json`.
* `watermark`: si se añade una marca de agua a la imagen generada. El valor predeterminado es `true`.
* `output_format`: especifica el formato de archivo de la imagen generada; admite `jpeg` (predeterminado) y `png`. Solo `doubao-seedream-5-0-pro-260628` y `doubao-seedream-5-0-lite-260128` lo admiten.
* `tools`: configura las herramientas que debe llamar el modelo; actualmente admite `web_search` (búsqueda web). Solo Seedream 5.0 Lite lo admite.
* `optimize_prompt_options`: configuración de optimización del texto de indicación. 5.0 Pro admite `standard`/`fast`; 5.0 Lite y 4.5 solo admiten `standard`; 4.0 admite `standard`/`fast`.
* `background`: solo es compatible con la edición de imagen única de 5.0 Pro. `transparent` requiere introducir una PNG con canal transparente, y `output_format` debe ser `png`; `opaque` corresponde a un fondo opaco normal.
* `layer_decomposition`: solo 5.0 Pro lo admite. Cuando se establece en `true`, debe introducirse una PNG/JPEG; puede no pasarse `prompt` para realizar la separación automática, o especificar elementos mediante lenguaje natural/``; `size` admite `auto`/`1K`/`1.5K`/`2K`. Este modo no se puede usar junto con grupos de imágenes, transmisión en flujo, búsqueda web ni `background`.
* `callback_url`: URL que necesita recibir el resultado de la devolución de llamada.
* `async`: si se procesa en modo asíncrono. Cuando se establece en `true`, la interfaz devuelve inmediatamente `task_id`, sin necesidad de proporcionar `callback_url`; posteriormente, obtenga el resultado mediante sondeo a través de `/seedream/tasks`.
Después de seleccionarlos, puede observar que también se genera el código correspondiente a la derecha, como se muestra en la imagen:
Haga clic en el botón «Try» para realizar una prueba; como se muestra en la imagen anterior, aquí obtenemos el siguiente resultado:
```json theme={null}
{
"success": true,
"task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
"trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
"data": [
{
"prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
"size": "2048x2048",
"image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
}
]
}
```
El resultado devuelto tiene varios campos en total, descritos a continuación:
* `success`, el estado actual de la tarea de generación de video.
* `task_id`, el ID actual de la tarea de generación de video.
* `trace_id`, el ID actual de seguimiento de la generación de video.
* `data`, la lista de resultados de la tarea actual de generación de imágenes.
* `image_url`, el enlace de la tarea actual de generación de imágenes.
* `prompt`, la palabra de indicación.
* `size`: los píxeles de la imagen generada
Podemos ver que hemos obtenido información satisfactoria de la imagen; solo necesitamos obtener la imagen SeeDream generada según la dirección del enlace de la imagen en `data` del resultado.
Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente; por ejemplo, el código CURL es el siguiente:
```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-lite-260128",
"prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'
```
## Tarea de edición de imágenes
Si deseas editar una imagen, primero el parámetro `image` debe incluir el enlace de la imagen que se necesita editar.
* model: el modelo utilizado para esta tarea de edición de imágenes; `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-lite-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` admiten todos entrada de imágenes.
* image: carga la imagen que se necesita editar, una o varias
El ejemplo de relleno es el siguiente:
El código correspondiente:
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedream/images"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedream-4-0-250828",
"prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
"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)
```
Haz clic en ejecutar y podrás ver que se obtiene inmediatamente un resultado, como el siguiente:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Se puede ver que el efecto generado es el efecto de editar la imagen original, y el resultado es similar al anterior.
## Descomposición de capas (Seedream 5.0 Pro)
La descomposición de capas dividirá una imagen de entrada en 1 imagen de fondo y hasta 16 capas PNG transparentes que pueden editarse de forma independiente. La siguiente solicitud permite al modelo identificar automáticamente los elementos principales; si necesitas especificar elementos, puedes añadir `prompt`, y también puedes utilizar coordenadas `` normalizadas en la palabra de indicación.
```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 '{
"model": "doubao-seedream-5-0-pro-260628",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"size": "2K",
"watermark": false
}'
```
Los `data` devueltos se ordenan de abajo hacia arriba según `z_index`. El `z_index` de la imagen de fondo es 0; las capas también incluyen `name`, `description` y `bounding_box.absolute`/`normalized`. Al recomponer utilizando coordenadas absolutas, escala las capas a `[right-left, bottom-top]`, colócalas en `[left, top]` y luego superpónlas en orden ascendente de `z_index`. Si la generación de cualquier capa falla, toda la descomposición falla.
## Salida en streaming
Cuando Lite/4.x establece `stream: true`, utiliza `accept: application/x-ndjson` en el encabezado de la solicitud. La interfaz devuelve línea por línea `image_generation.partial_succeeded` o `image_generation.partial_failed`, y finalmente devuelve el único evento `image_generation.completed` y el `usage` final; solo el evento de finalización activa una facturación. El modo de streaming no puede utilizarse junto con `async` o `callback_url`.
## Devolución de llamada asíncrona
Dado que la API de generación de imágenes SeeDream tarda relativamente mucho tiempo en generar, aproximadamente 1-2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión abierta, lo que provoca un consumo adicional de recursos del sistema; por lo tanto, esta API también proporciona soporte para devoluciones de llamada asíncronas.
El flujo general es: cuando el cliente inicia una solicitud, especifica adicionalmente un campo `callback_url`; después de que el cliente inicia la solicitud API, la API devolverá inmediatamente un resultado, que incluye información de un campo `task_id`, que representa el ID de la tarea actual. Cuando la tarea se completa, el resultado de la generación de imágenes se enviará mediante POST JSON al `callback_url` especificado por el cliente, que también incluye el campo `task_id`, de modo que los resultados de la tarea pueden asociarse mediante el ID.
Si no tienes una dirección pública disponible para la devolución de llamada, tampoco puedes especificar `callback_url`, sino establecer el campo `async` en `true` en la solicitud. En este momento, la interfaz también devolverá inmediatamente `task_id`, pero no enviará el resultado; debes llevar este `task_id` para llamar a la interfaz `/seedream/tasks` y sondear el estado de la tarea para obtener el resultado final.
A continuación, comprenderemos mediante ejemplos cómo operar específicamente.
Haz clic en ejecutar y podrás ver que se obtiene inmediatamente un resultado, como el siguiente:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
El contenido es el siguiente:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Mantén sin cambios la pose del modelo y la forma fluida de la prenda líquida. Cambia el material de la ropa de metal plateado a agua (o vidrio) completamente transparente. A través del flujo líquido, los detalles de la piel del modelo son visibles. El efecto de luz y sombra cambia de reflexión a refracción.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Se puede ver que hay un campo `task_id` en el resultado; los demás campos son similares a los anteriores, y la asociación de tareas se puede lograr mediante este campo.
## Manejo de errores
Al llamar a la API, si se produce un error, la API devolverá el código de error y la información correspondientes. Por ejemplo:
* `400 token_mismatched`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o no válidos.
* `400 api_not_implemented`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o no válidos.
* `401 invalid_token`: No autorizado, token de autorización no válido o faltante.
* `429 too_many_requests`: Demasiadas solicitudes, has superado el límite de velocidad.
* `500 api_error`: Error interno del servidor, algo salió mal en el servidor.
### Ejemplo de respuesta de error
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusión
A través de este documento, ya has aprendido cómo utilizar SeeDream Images Generation API para generar imágenes introduciendo textos de indicación. Esperamos que este documento pueda ayudarte a integrar y utilizar mejor esta API. Si tienes alguna pregunta, no dudes en ponerte en contacto con nuestro equipo de soporte técnico.