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

📘 Documentación completa: SeeDream Images Generation API →

​

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/<bbox>; 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:

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

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:

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:

{
  "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 <bbox> normalizadas en la palabra de indicación.

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:

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

{
  "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.