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

📘 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, 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:

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

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:

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:

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

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

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

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

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

Proceso de solicitud

Uso básico

Editar tarea de imagen

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión

​Proceso de solicitud

​Uso básico

​Editar tarea de imagen

​Callback asíncrono

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de solicitud

Uso básico

Editar tarea de imagen

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión