Skip to main content
Este documento presentará una guía sobre la integración de la API de generación de imágenes Flux, que permite generar imágenes oficiales de Flux mediante la entrada de parámetros personalizados.

​
Proceso de solicitud

Para utilizar la API de generación de imágenes Flux, primero dirígete a la consola de Ace Data Cloud para obtener tu token de API y guardarlo 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 Flux →

​
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, necesitas 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:
  • action: la acción de la tarea de generación de imágenes.
  • size: el tamaño de la imagen generada. Las series flux-2-flex / flux-2-pro / flux-2-max deben recibir la proporción de la imagen (como 1:1, 16:9), no se aceptan dimensiones en píxeles como 1024x1024, y si se omite, se devolverá un error 400.
  • count: la cantidad de imágenes a generar, el valor predeterminado es 1, este parámetro solo es válido para tareas de generación de imágenes, no es válido para tareas de edición.
  • prompt: la palabra clave.
  • model: el modelo de generación, por defecto flux-dev; los últimos modelos insignia son flux-2-pro, flux-2-max (con mayor calidad de imagen, debe ir acompañado de la proporción de imagen size).
  • callback_url: la URL donde se necesita el resultado de la llamada.
  • async: opcional, si se establece en true, la interfaz devolverá inmediatamente task_id, sin necesidad de proporcionar callback_url, y luego se puede consultar el resultado mediante la interfaz de consulta de tareas correspondiente.
El parámetro size tiene algunas restricciones especiales, que se dividen principalmente en dos tipos: proporción de ancho x alto y proporción de imagen x:y, que son las siguientes: Proporciones de imagen de referencia: “21:9”, “16:9”, “4:3”, “3:2”, “1:1”, “2:3”, “3:4”, “9:16”, “9:21”. Después de seleccionar los parámetros, el código correspondiente se generará automáticamente a la derecha. Antes de copiar, asegúrate de que el encabezado de autorización use tu propia clave de API; no deben aparecer credenciales reales en la documentación y capturas de pantalla. Haz clic en el botón “Try” para realizar la prueba, y aquí obtuvimos el siguiente resultado:
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, 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.
Podemos ver que hemos obtenido información de imagen satisfactoria, solo necesitamos obtener la imagen generada de Flux a través de la dirección del enlace de imagen en data. Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código de CURL es el siguiente:

​
Tarea de edición de imágenes

Si deseas editar una imagen, primero el parámetro image_url debe incluir el enlace de la imagen que deseas editar, en este caso, action solo admite edit, y puedes especificar el siguiente contenido:
  • model: el modelo utilizado para la tarea de edición de imágenes, admite flux-dev, flux-pro, flux-kontext-pro, flux-kontext-max, flux-2-flex, flux-2-pro, flux-2-max.
  • image_url: la imagen que necesitas editar.
Un ejemplo de llenado es el siguiente:

Una vez completado, se generó automáticamente el siguiente código:

El código correspondiente:
Al hacer clic en ejecutar, se puede observar que se obtiene un resultado inmediato, como el siguiente:
Se puede ver que el efecto generado es el resultado de editar la imagen original, similar al anterior.

​
Callback Asíncrono

Debido a que el tiempo de generación de la API de Flux 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 tanto, 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 realiza la solicitud a la API, esta devolverá inmediatamente un resultado que incluye un campo task_id, que representa el ID de la tarea actual. Cuando la tarea se completa, el resultado de la imagen generada se enviará al callback_url especificado por el cliente en formato JSON POST, que también incluirá el campo task_id, de modo que el resultado de la tarea se pueda asociar mediante el ID. A continuación, entenderemos cómo operar específicamente a través de un ejemplo. Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, y los desarrolladores deben reemplazarlo con la URL de su propio servidor HTTP. Para facilitar la demostración, se utiliza un sitio web de ejemplo de Webhook público https://webhook.site/, al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen: Copie esta URL y podrá usarla como Webhook, el ejemplo aquí es https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. A continuación, podemos establecer el campo callback_url como la URL de Webhook mencionada anteriormente, al mismo tiempo que llenamos los parámetros correspondientes, el contenido específico se muestra en la imagen:

Al hacer clic en ejecutar, se puede observar que se obtiene inmediatamente un resultado, como se muestra a continuación:
Después de un momento, podemos observar el resultado de la imagen generada en https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, como se muestra en la imagen: El contenido es el siguiente:
Se puede ver que en el resultado hay un campo task_id, y los otros campos son similares a los mencionados anteriormente, a través de este campo se puede realizar 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 y la información correspondiente. 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

​
Conclusión

A través de este documento, ha aprendido cómo utilizar la API de Flux Images Generation 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.