> ## 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 la API de generación de imágenes SeeDream
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
Este documento presentará una forma de integración de la API de generación de imágenes SeeDream, que permite generar imágenes oficiales de SeeDream mediante la entrada de parámetros personalizados.
## Proceso de solicitud
Para utilizar la API de generación de imágenes SeeDream, primero dirígete a [la consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu token de API, que debes guardar como respaldo.
Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual.
**Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno para cada servicio.** La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en [la consola](https://platform.acedata.cloud/console/coin).
> 📘 Documentación completa: [API de generación de imágenes SeeDream →](https://platform.acedata.cloud/documents/seedream-images)
## Uso básico
Primero, es importante entender la forma básica de uso, que consiste en ingresar la palabra clave `prompt`, la acción de generación `action`, y el tamaño de la imagen `size`, para obtener el resultado procesado. Primero, necesitamos pasar un campo `action`, cuyo valor será `generate`, y luego también necesitamos ingresar la palabra clave, el contenido específico es el siguiente:
Aquí podemos ver que hemos configurado los encabezados de la solicitud, que incluyen:
* `accept`: el formato de respuesta que deseas recibir, aquí se establece como `application/json`, es decir, en formato JSON.
* `authorization`: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.
Además, se ha configurado el cuerpo de la solicitud, que incluye:
* `prompt`: la palabra clave.
* `model`: el modelo de generación, por defecto `doubao-seedream-5-0-260128` (SeeDream 5.0 Lite, el más reciente). Soporta `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`. Entre ellos, `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) es el modelo insignia de imagen única, que solo genera una imagen, **no soporta generación de imágenes en secuencia (`sequential_image_generation`), modo de flujo (`stream`) ni búsqueda en línea (`tools`)**. **El `model` debe ser pasado como una cadena de modelo completa (por ejemplo, `doubao-seedream-5-0-260128`), pasar `doubao-seedream-5.0-lite` como abreviatura devolverá un error 400.**
* `image`: información de la imagen de entrada, soporta URL o codificación Base64. Entre ellos, `doubao-seedream-5-0-pro-260628` soporta entrada de una o varias imágenes (de 2 a 10 imágenes, a partir de la segunda se cobrará por imagen), `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` soportan entrada de una o varias imágenes, `doubao-seededit-3-0-i2i-250628` solo soporta entrada de una imagen, `doubao-seedream-3-0-t2i-250415` no soporta este parámetro.
* `size`: especifica la información del tamaño de la imagen generada, soporta 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 en lenguaje natural en el prompt. **Los presets soportados varían según el modelo**: `doubao-seedream-5-0-pro-260628` soporta `1K`/`2K`; `doubao-seedream-5-0-260128` soporta `2K`/`3K`/`4K`; `doubao-seedream-4-5-251128` solo soporta `2K`/`4K`; `doubao-seedream-4-0-250828` soporta `1K`/`2K`/`4K`; `doubao-seedream-3-0-t2i-250415` y `doubao-seededit-3-0-i2i-250628` **no soportan presets**, solo aceptan la forma 2. Forma 2 | Especificar los valores de píxeles de ancho y alto de la imagen generada: por defecto `2048x2048`, el rango de valores de píxeles totales y relación de aspecto varía según el modelo (por ejemplo, el rango total de píxeles de 5.0 Pro es \[921600, 4194304], el límite inferior de 5.0 Lite / 4.5 es 3,686,400, el límite inferior de 4.0 es 921,600, y el rango de 3.0-t2i / seededit-3.0-i2i es \[512x512, 2048x2048]).
* `seed`: semilla de número aleatorio, utilizada para controlar la aleatoriedad del contenido generado por el modelo. El rango de valores es \[-1, 2147483647]. **Solo `doubao-seedream-3-0-t2i-250415` soporta este parámetro**.
* `sequential_image_generation`: generación de imágenes en grupo: un conjunto de imágenes relacionadas generadas en base a tu contenido ingresado. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` soportan este parámetro, por defecto `disabled`.
* `stream`: controla si se activa el modo de salida en flujo. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` soportan este parámetro, por defecto es `false`.
* `guidance_scale`: grado de coincidencia entre el resultado de salida del modelo y el prompt, cuanto mayor sea el valor, mayor será la correlación. Rango de valores \[1, 10]. `doubao-seedream-3-0-t2i-250415` tiene un valor por defecto de 2.5, `doubao-seededit-3-0-i2i-250628` tiene un valor por defecto de 5.5, otros modelos no lo soportan.
* `response_format`: especifica el formato de retorno de la imagen generada. Por defecto es `url`, también soporta `b64_json`.
* `watermark`: si se debe agregar una marca de agua a la imagen generada. Por defecto es `true`.
* `output_format`: especifica el formato de archivo de la imagen generada, soporta `jpeg` (por defecto) y `png`. Solo `doubao-seedream-5-0-pro-260628` y `doubao-seedream-5-0-260128` lo soportan.
* `tools`: configura las herramientas que el modelo debe llamar, actualmente soporta `web_search` (búsqueda en línea). Solo `doubao-seedream-5-0-260128` lo soporta.
* `callback_url`: URL donde se necesita el resultado de la llamada.
* `async`: si se debe procesar en modo asíncrono. Si se establece en `true`, la interfaz devuelve inmediatamente `task_id`, sin necesidad de proporcionar `callback_url`, y luego se puede obtener el resultado mediante la consulta a `/seedream/tasks`.
Después de seleccionar, puedes ver que a la derecha también se ha generado el código correspondiente, como se muestra en la imagen:
Haz clic en el botón "Try" para realizar la prueba, como se muestra en la imagen anterior, aquí hemos obtenido el siguiente resultado:
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "Una toma de producto en estudio fotorrealista de una botella de perfume de vidrio esmerilado sobre pizarra negra húmeda, luz clave de softbox única, gotas de agua, fondo oscuro y melancólico, 85mm macro.",
"size": "2048x2048",
"image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
}
]
}
```
返回结果一共有多个字段，介绍如下：
* `success`，el estado de la tarea de generación de video en este momento.
* `task_id`，el ID de la tarea de generación de video en este momento.
* `trace_id`，el ID de seguimiento de la generación de video en este momento.
* `data`，la lista de resultados de la tarea de generación de imágenes en este momento.
* `image_url`，el enlace de la tarea de generación de imágenes en este momento.
* `prompt`，la palabra clave.
* `size`: los píxeles de la imagen generada.
Se puede ver que hemos obtenido información de imagen satisfactoria, solo necesitamos obtener la imagen generada de SeeDream a través de la dirección del enlace de la imagen en `data`.
Además, si deseas generar el código correspondiente, puedes copiarlo directamente, por ejemplo, el código de 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-260128",
"prompt": "Una toma de producto en estudio fotorrealista de una botella de perfume de vidrio esmerilado sobre pizarra negra húmeda, luz clave de softbox única, gotas de agua, fondo oscuro y melancólico, 85mm macro."
}'
```
## Editar tarea de imagen
Si deseas editar una imagen, primero el parámetro `image` debe incluir el enlace de la imagen que necesitas editar.
* model: el modelo utilizado para la tarea de edición de imágenes, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` admiten entrada de una o varias imágenes, `doubao-seededit-3-0-i2i-250628` solo admite entrada de una imagen.
* image: subir la imagen que necesita ser editada, una o varias.
Ejemplo de llenado:
Código correspondiente:
```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": "Mantener la pose del modelo y la forma del vestido líquido sin cambios. Cambiar el material de la ropa de metal plateado a agua completamente transparente (o vidrio). A través del flujo del líquido, los detalles de la piel del modelo son visibles. El efecto de luz y sombra cambia de reflexión a refracción.",
"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)
```
Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como el siguiente:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Mantener la pose del modelo y la forma del vestido líquido sin cambios. Cambiar el material de la ropa de metal plateado a agua completamente transparente (o vidrio). A través del flujo del 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 el efecto generado es el resultado de editar la imagen original, similar al anterior.
## Callback asíncrono
Dado que el tiempo de generación de la API de generación de imágenes de SeeDream es relativamente largo, aproximadamente de 1 a 2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema, por lo que esta API también ofrece soporte para callbacks asíncronos.
El flujo general es: cuando el cliente inicia la solicitud, se especifica un campo adicional `callback_url`, después de que el cliente inicia la solicitud de API, la API devolverá inmediatamente un resultado que incluye un campo de información `task_id`, que representa el ID de la tarea actual. Cuando la tarea se complete, el resultado de la imagen generada se enviará a la `callback_url` especificada por el cliente en forma de JSON POST, que también incluye el campo `task_id`, de modo que el resultado de la tarea se pueda asociar mediante el ID.
Si no tienes una dirección pública disponible para el callback, también puedes no especificar `callback_url`, sino establecer el campo `async` en `true` en la solicitud. En este caso, la interfaz también devolverá inmediatamente el `task_id`, pero no enviará el resultado, necesitarás llevar ese `task_id` para llamar a la interfaz `/seedream/tasks` y consultar el estado de la tarea para obtener el resultado final.
A continuación, veamos un ejemplo para entender cómo operar específicamente.
Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, 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": "Mantener la pose del modelo y la forma del vestido líquido sin cambios. Cambiar el material de la ropa de metal plateado a agua completamente transparente (o vidrio). A través del flujo del 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 en el resultado hay un campo `task_id`, los otros campos son similares a los anteriores, y a través de este campo se puede realizar la asociación de tareas.
## Manejo de errores
Al llamar a la API, si se encuentra un error, la API devolverá el código de error correspondiente y la información. Por ejemplo:
* `400 token_mismatched`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
* `400 api_not_implemented`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
* `401 invalid_token`: No autorizado, token de autorización inválido o faltante.
* `429 too_many_requests`: Demasiadas solicitudes, has superado el límite de tasa.
* `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": "la recuperación falló"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusión
A través de este documento, usted ha comprendido cómo utilizar la API de generación de imágenes SeeDream para generar imágenes mediante la entrada de palabras clave. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.