Instrucciones de integración de la API de generación de imágenes SeeDream

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 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 por 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.

📘 Documentación completa: API de generación de imágenes SeeDream →

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, cuyo 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 (también acepta el alias oficial 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 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). model debe recibir la cadena completa del modelo (como doubao-seedream-5-0-260128), pasar doubao-seedream-5.0-lite u otras abreviaturas devolverá un error 400.
image: información de la imagen de entrada, soporta URL o codificación Base64. 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.
size: especifica la información del tamaño de la imagen generada, soporta las siguientes dos formas, 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/1.5K/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. 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, 4624220], el límite inferior de 5.0 Lite / 4.5 es 3,686,400, y el límite inferior de 4.0 es 921,600).
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.
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 SeeDream 5.0 Lite lo soporta.
optimize_prompt_options: configuración de optimización de palabras clave. 5.0 Pro soporta standard/fast; 5.0 Lite y 4.5 solo soportan standard; 4.0 soporta standard/fast.
background: solo soportado por 5.0 Pro para edición de imagen única. transparent requiere que se ingrese una PNG con canal de transparencia, y output_format debe ser png; opaque es un fondo normal y opaco.
layer_decomposition: solo soportado por 5.0 Pro. Al establecer en true, se debe ingresar una PNG/JPEG, se puede omitir prompt para dividir automáticamente, o usar lenguaje natural/<bbox> para especificar elementos; size soporta auto/1K/1.5K/2K. Este modo no puede usarse junto con generación de imágenes en grupo, flujo, búsqueda en línea o background.
callback_url: URL donde se necesita el resultado de la llamada.
async: si se debe procesar en modo asíncrono. Al establecer 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, se puede observar 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 pruebas, como se muestra en la imagen anterior, aquí hemos obtenido el siguiente resultado:

{
  "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"
    }
  ]
}

Los resultados devueltos tienen varios campos, que se describen a continuación:

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:

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."
}'

Tarea de edición de imágenes

Si deseas editar una imagen, primero el parámetro image debe contener el enlace de la imagen que necesitas editar.

model: el modelo utilizado para esta tarea de edición de imágenes, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 todos admiten entrada de imagen.
image: subir la imagen que necesita ser editada, una o varias.

Ejemplo de llenado:

Código correspondiente:

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": "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 sigue:

{
  "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 efecto de edición de la imagen original, 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 se pueden editar de forma independiente. La siguiente solicitud permite que el modelo reconozca automáticamente los elementos principales; si se desea especificar elementos, se puede agregar prompt, también se pueden usar coordenadas normalizadas <bbox> en la palabra clave.

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 por z_index de abajo hacia arriba. El z_index de la imagen de fondo es 0; las capas también incluyen name, description y bounding_box.absolute/normalized. Al reorganizar con coordenadas absolutas, se escalan las capas a [right-left, bottom-top], se colocan en [left, top], y luego se apilan en orden ascendente por z_index. Si alguna capa falla en la generación, toda la descomposición falla.

Salida en flujo

Lite/4.x establece stream: true, en cuyo caso el encabezado de la solicitud utiliza accept: application/x-ndjson. La interfaz devuelve línea por línea image_generation.partial_succeeded o image_generation.partial_failed, y finalmente devuelve un evento único image_generation.completed y el usage final; solo el evento de finalización activa una facturación. El modo de flujo no puede usarse junto con async o callback_url.

Callback asíncrono

Debido a 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 contiene un campo de información task_id, que representa el ID de la tarea actual. Cuando la tarea se completa, 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 sondear el estado de la tarea para obtener el resultado final. A continuación, a través de un ejemplo, entenderemos cómo operar específicamente. Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como sigue:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

El contenido es el siguiente:

```json
{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Mantén la pose del modelo y la forma fluida de la prenda líquida sin cambios. Cambia el material de la ropa de metal plateado a agua completamente transparente (o vidrio). 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 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 lograr la asociación de tareas.

Manejo de errores

Al llamar a la API, si se encuentra con 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, ha superado el límite de tasa.
500 api_error: Error interno del servidor, algo salió mal en el servidor.

Ejemplo de respuesta de error

{
  "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, ha comprendido cómo utilizar la API de generación de imágenes SeeDream, que puede generar imágenes a través de 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.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

Coding

Instrucciones de integración de la API de generación de imágenes SeeDream

Proceso de solicitud

Uso básico

Tarea de edición de imágenes

Descomposición de capas (Seedream 5.0 Pro)

Salida en flujo

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión

​Proceso de solicitud

​Uso básico

​Tarea de edición de imágenes

​Descomposición de capas (Seedream 5.0 Pro)

​Salida en flujo

​Callback asíncrono

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de solicitud

Uso básico

Tarea de edición de imágenes

Descomposición de capas (Seedream 5.0 Pro)

Salida en flujo

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión