Saltar al contenido principal
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, primero debe ir a la página correspondiente de API de generación de imágenes SeeDream para solicitar el servicio correspondiente. Una vez en la página, haga clic en el botón “Acquire”, como se muestra en la imagen: Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión que lo invita a registrarse e iniciar sesión. Después de iniciar sesión o registrarse, volverá automáticamente a la página actual. En la primera solicitud, se le otorgará un límite gratuito que le permitirá utilizar la API de forma gratuita.

​
Uso básico

Primero, debe comprender 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, necesita pasar un campo action, cuyo valor es 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 desea recibir, aquí se establece como application/json, es decir, formato JSON.
  • authorization: la clave para llamar a la API, que puede seleccionarse directamente después de la solicitud.
Además, se ha configurado el cuerpo de la solicitud, que incluye:
  • prompt: palabra clave.
  • model: modelo de generación, por defecto doubao-seedream-4.0.
  • image: información de la imagen de entrada, admite URL o codificación Base64. Entre ellos, doubao-seedream-4.5, doubao-seedream-4.0 admiten entrada de una o varias imágenes, doubao-seededit-3.0-i2i solo admite entrada de una imagen, doubao-seededit-3.0-t2i no admite este parámetro.
  • size: especifica la información del tamaño de la imagen generada, admite 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, la forma o el uso de la imagen en lenguaje natural en el prompt, y el modelo determinará el tamaño de la imagen generada. Forma 2 | Especificar los valores de píxeles de ancho y alto de la imagen generada: valor predeterminado: 2048x2048, el valor predeterminado varía según el modelo.
  • 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, doubao-seededit-3.0-i2i admiten este parámetro.
  • sequential_image_generation: conjunto de imágenes: imágenes relacionadas generadas en función del contenido que ingresó. Solo doubao-seedream-4.5, doubao-seedream-4.0 admiten este parámetro, predeterminado disabled.
  • stream: controla si se activa el modo de salida en streaming. Solo doubao-seedream-4.5, doubao-seedream-4.0 admiten este parámetro, el valor predeterminado es false.
  • guidance_scale: grado de consistencia entre el resultado de salida del modelo y el prompt, grado de libertad de la imagen generada, también conocido como peso del texto; cuanto mayor sea el valor, menor será la libertad del modelo y mayor será la correlación con la palabra clave ingresada por el usuario. Rango de valores: [1, 10]. doubao-seedream-3.0-t2i valor predeterminado 2.5, doubao-seededit-3.0-i2i valor predeterminado 5.5, otros no admiten.
  • response_format: especifica el formato de retorno de la imagen generada. El valor predeterminado es url, también admite b64_json.
  • watermark: si se debe agregar una marca de agua a la imagen generada. El valor predeterminado es true.
  • callback_url: URL donde se necesita el resultado de la llamada.
Después de seleccionar, puede ver que también se ha generado el código correspondiente a la derecha, como se muestra en la imagen:

Haga 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": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}
El resultado devuelto tiene varios campos, que se describen a continuación:
  • success, el estado de la tarea de generación de video en este momento.
  • task_id, ID de la tarea de generación de video en este momento.
  • trace_id, ID de seguimiento de la generación de video en este momento.
  • data, lista de resultados de la tarea de generación de imágenes en este momento.
    • image_url, enlace de la tarea de generación de imágenes en este momento.
    • prompt, palabra clave.
    • size: píxeles de la imagen generada.
Podemos 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 imagen en data del resultado. Además, si desea generar el código de integración correspondiente, puede 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-4-0-250828",
  "prompt": "a white siamese cat"
}'

​
Tarea de edición de imágenes

Si desea editar una imagen, primero debe pasar el enlace de la imagen que necesita editar en el parámetro image.
  • model: el modelo utilizado para esta tarea de edición de imágenes, actualmente admite doubao-seedream-4.5, doubao-seedream-4.0 que admiten entrada de una o varias imágenes, doubao-seededit-3.0-i2i solo admite entrada de una imagen.
  • image: subir la imagen que necesita editar, una o varias.
Ejemplo de llenado a continuación:

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 líquido, son visibles los detalles de la piel del modelo. 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, puede ver que se obtiene un resultado de inmediato, como se muestra a continuación: 
{
    "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 el efecto generado es una edición de la imagen original, el resultado es similar al anterior.

​
Callback asíncrono

Dado que el tiempo de generación de la API de SeeDream Images Generation 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, especifica un campo adicional callback_url, después de que el cliente inicia la solicitud de la 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 completa, el resultado de la imagen generada se enviará a la callback_url especificada por el cliente en formato JSON POST, que también incluye el campo task_id, de esta manera el resultado de la tarea se puede asociar a través del ID. A continuación, entenderemos cómo operar específicamente a través de un ejemplo. Al hacer clic en ejecutar, se puede observar que se obtiene inmediatamente un resultado, como se muestra a continuación: 
{
  "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 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, a través de este campo se puede lograr la asociación de la tarea.

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