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

Este documento presenta una guía para la 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 usar la API, primero debe solicitar el servicio correspondiente en la página de SeeDream Images Generation API. Al ingresar, 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 para registrarse o ingresar. Después de iniciar sesión o registrarse, volverá automáticamente a esta página. Al solicitar por primera vez, se otorgará un crédito gratuito para usar la API sin costo.

Uso básico

Primero, conozcamos el modo básico de uso: ingresando la palabra clave prompt, la acción de generación action y el tamaño de la imagen size, se obtiene el resultado procesado. Inicialmente, debe enviar un campo action con el valor generate, además de ingresar la palabra clave. El contenido específico es el siguiente:

Aquí configuramos los encabezados de la solicitud (Request Headers), que incluyen:

accept: formato de respuesta esperado, aquí se usa application/json para recibir JSON.
authorization: clave para llamar a la API, que puede seleccionarse tras la solicitud.

También configuramos el cuerpo de la solicitud (Request Body), que incluye:

prompt: palabra clave o descripción.
model: modelo de generación, por defecto doubao-seedream-5.0-lite. Soporta doubao-seedream-5.0-lite (el más reciente), doubao-seedream-4.5, doubao-seedream-4.0, doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i.
image: información de imagen de entrada, soporta URL o codificación Base64. Los modelos doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 soportan entrada de una o varias imágenes; doubao-seededit-3.0-i2i solo una imagen; doubao-seedream-3.0-t2i no soporta este parámetro.
size: especifica el tamaño de la imagen generada, soporta dos modos que no pueden mezclarse. Modo 1 | especificar resolución y describir la relación de aspecto en el prompt con lenguaje natural. Los presets soportados varían según el modelo: doubao-seedream-5.0-lite soporta 2K/3K/4K; doubao-seedream-4.5 solo 2K/4K; doubao-seedream-4.0 soporta 1K/2K/4K; doubao-seedream-3.0-t2i y doubao-seededit-3.0-i2i no soportan presets, solo aceptan modo 2. Modo 2 | especificar el ancho y alto en píxeles: por defecto 2048x2048, el rango de píxeles totales y relación de aspecto varía según el modelo (por ejemplo, para 5.0 / 4.5 el mínimo es 3,686,400 píxeles, para 4.0 es 921,600, para 3.0-t2i / seededit-3.0-i2i el rango es [512x512, 2048x2048]).
seed: semilla aleatoria para controlar la aleatoriedad de la generación. Rango [-1, 2147483647]. Solo soportado por doubao-seedream-3.0-t2i.
sequential_image_generation: generación de conjunto de imágenes relacionadas basadas en el contenido ingresado. Soportado por doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, por defecto disabled.
stream: controla si se activa el modo de salida en streaming. Soportado por doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, por defecto false.
guidance_scale: grado de correspondencia entre el resultado del modelo y el prompt, valores mayores indican mayor correlación. Rango [1, 10]. Valor por defecto 2.5 para doubao-seedream-3.0-t2i, 5.5 para doubao-seededit-3.0-i2i, no soportado en otros modelos.
response_format: formato de retorno de la imagen generada. Por defecto url, también soporta b64_json.
watermark: si se añade marca de agua en la imagen generada. Por defecto true.
output_format: formato del archivo generado, soporta jpeg (por defecto) y png. Solo soportado por doubao-seedream-5.0-lite.
tools: configuración de herramientas que el modelo puede usar, actualmente soporta web_search (búsqueda en línea). Solo soportado por doubao-seedream-5.0-lite.
callback_url: URL para recibir el resultado mediante callback.

Tras seleccionar, se genera el código correspondiente a la derecha, como se muestra:

Haga clic en el botón “Try” para probar. En la imagen anterior, obtenemos 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.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}

El resultado incluye varios campos, descritos a continuación:

success: estado de la tarea de generación de imagen.
task_id: ID de la tarea de generación.
trace_id: ID de seguimiento de la tarea.
data: lista de resultados de la tarea de generación de imagen.
- image_url: enlace a la imagen generada.
- prompt: palabra clave o descripción.
- size: tamaño en píxeles de la imagen generada.

Como puede ver, obtenemos la información de la imagen generada, solo debe usar el enlace en data para acceder a la imagen SeeDream generada. Si desea generar código de integración, puede copiarlo directamente. Por ejemplo, el código CURL es:

curl -X POST 'https://api.xhuoapi.ai/v1/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 proporcionar el parámetro image con el enlace de la imagen a editar.

model: modelo usado para la edición, doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 soportan entrada de una o varias imágenes; doubao-seededit-3.0-i2i solo una imagen.
image: imagen o imágenes a editar.

Ejemplo de llenado:

Código correspondiente:

import requests

url = "https://api.xhuoapi.ai/v1/flux/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)

Al ejecutar, se obtiene inmediatamente un resultado como:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Como puede ver, el resultado es una edición de la imagen original, similar al ejemplo anterior.

Callback asíncrono

Dado que la generación de imágenes con la API SeeDream puede tardar entre 1 y 2 minutos, si la API no responde durante mucho tiempo, la conexión HTTP se mantiene abierta, consumiendo recursos del sistema. Por ello, la API soporta callbacks asíncronos. El flujo es: el cliente incluye un campo callback_url al hacer la solicitud. La API responde inmediatamente con un resultado que contiene un task_id que identifica la tarea. Cuando la tarea finaliza, el resultado de la imagen generada se envía mediante POST en formato JSON al callback_url especificado, incluyendo también el task_id para relacionar la respuesta con la tarea. Veamos un ejemplo: Al ejecutar, se obtiene inmediatamente:

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

Contenido:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Como puede ver, el resultado contiene un campo task_id y otros campos similares a los anteriores, permitiendo relacionar la respuesta con la tarea.

Manejo de errores

Al llamar a la API, si ocurre un error, esta devuelve un código y mensaje de error correspondiente. Por ejemplo:

400 token_mismatched: solicitud incorrecta, posiblemente por parámetros faltantes o inválidos.
400 api_not_implemented: solicitud incorrecta, posiblemente por 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, se ha excedido el límite de tasa.
500 api_error: error interno del servidor.

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

Con este documento, ha aprendido cómo usar la API de generación de imágenes SeeDream para crear imágenes a partir de palabras clave. Esperamos que esta guía le ayude a integrar y utilizar la API de manera efectiva. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico.

Documentation Index

​Proceso de solicitud

​Uso básico

​Tarea de edición de imágenes

​Callback asíncrono

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión