Instrucciones de integración de la API de Generación de Imágenes Flux

Este artículo presentará unas instrucciones de integración de la API de Generación de Imágenes Flux, que permite generar imágenes oficiales de Flux mediante la introducción de parámetros personalizados.

Proceso de solicitud

Para utilizar la API de Generación de Imágenes Flux, primero obtenga su API Token en la Consola de Ace Data Cloud y guárdelo como respaldo.

Si aún no ha iniciado sesión o no se ha registrado, será redirigido 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 solo API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitarlo por separado para cada servicio. La primera solicitud incluirá créditos gratuitos para una experiencia sin costo; cuando los créditos sean insuficientes, puede recargar saldo general en la consola.

📘 Documentación completa: Flux Images Generation API →

Uso básico

Primero entendamos el método de uso básico: introduciendo el texto de solicitud prompt, la acción de generación action y el tamaño de imagen size, se puede obtener el resultado procesado. Primero es necesario pasar simplemente un campo action, cuyo valor es generate, y luego también necesitamos introducir el texto de solicitud; el contenido específico es el siguiente:

Aquí podemos ver que configuramos los Request Headers, incluyendo:

accept: qué formato de resultado de respuesta se desea recibir; aquí se completa como application/json, es decir, formato JSON.
authorization: la clave para llamar a la API, que se puede seleccionar directamente en la lista desplegable después de solicitarla.

Además, configuramos el Request Body, incluyendo:

action: la acción de esta tarea de generación de imágenes.
size: el tamaño del resultado de generación de imágenes. Las series flux-2-flex / flux-2-pro / flux-2-max deben recibir una proporción de imagen (como 1:1, 16:9), no aceptan tamaños en píxeles como 1024x1024; si se omite, devolverá 400.
count: la cantidad de imágenes generadas; el valor predeterminado es 1. Este parámetro solo es válido para tareas de generación de imágenes y no es válido para tareas de edición.
prompt: texto de solicitud.
model: modelo de generación, el valor predeterminado es flux-dev; los últimos modelos insignia son flux-2-pro, flux-2-max (mayor calidad de imagen, requiere la proporción de imagen size).
callback_url: la URL que necesita recibir el resultado de la devolución de llamada.
async: opcional; cuando se establece en true, la interfaz devuelve inmediatamente task_id, sin necesidad de proporcionar callback_url; posteriormente, se obtienen los resultados mediante sondeo a través de la interfaz de consulta de tareas correspondiente.

El parámetro size tiene algunas restricciones especiales, principalmente se divide en dos tipos: proporción de ancho y alto width x height y proporción de imagen x:y; los detalles son los siguientes:

Modelo	Rango
flux-dev	Admite proporción de ancho y alto 1024x1024, 1024x1792, 1792x1024, o proporción de imagen
flux-pro	Admite proporción de ancho y alto 1024x1024, 1024x1792, 1792x1024, o proporción de imagen
flux-2-flex	Solo admite proporción de imagen
flux-2-pro	Solo admite proporción de imagen
flux-2-max	Solo admite proporción de imagen
flux-kontext-pro	Solo admite proporción de imagen
flux-kontext-max	Solo admite proporción de imagen

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 copiarlo, confirme que el encabezado de autorización utiliza su propia API Key; la documentación y las capturas de pantalla no deben mostrar credenciales reales. Haga clic en el botón «Try» para realizar una prueba; aquí obtenemos el siguiente resultado:

{
  "success": true,
  "task_id": "5456c749-3bbb-4f10-9eb8-cfbcac297500",
  "trace_id": "ae4eecb8-1dd6-45b4-bfb3-a1c48872536e",
  "data": [
    {
      "image_url": "https://cdn.acedata.cloud/assets/examples/flux/5456c749-3bbb-4f10-9eb8-cfbcac297500-d0ef60485f73.jpg"
    }
  ]
}

El resultado devuelto contiene varios campos, que se presentan 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 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, texto de solicitud.

Podemos ver que hemos obtenido información satisfactoria de la imagen; solo necesitamos obtener la imagen Flux generada según la dirección del enlace de imagen en data dentro del resultado. Además, si desea generar el código de integración correspondiente, puede copiarlo directamente; por ejemplo, el código CURL es el siguiente:

curl -X POST 'https://api.acedata.cloud/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
  "model": "flux-2-pro",
  "size": "1:1"
}'

Tarea de edición de imágenes

Si desea editar una imagen, primero el parámetro image_url debe incluir el enlace de la imagen que se necesita editar; en este momento, action solo admite edit, y se puede especificar el siguiente contenido:

model: el modelo utilizado por esta 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: cargar la imagen que necesita editarse.

El ejemplo de llenado es el siguiente:

Después de completarlo, se genera automáticamente el siguiente código:

El código correspondiente:

import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.acedata.cloud/ytj2qy.png"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Haga clic en ejecutar y podrá descubrir que se obtendrá inmediatamente un resultado, como el siguiente:

{
  "success": true,
  "task_id": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "timings": 1752744073
    }
  ]
}

Se puede ver que el efecto generado es el de editar la imagen original, y el resultado es similar al descrito anteriormente.

Devolución de llamada asíncrona

Dado que el tiempo de generación de Flux Images Generation API es relativamente largo, aproximadamente de 1 a 2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión abierta, lo que provocará un consumo adicional de recursos del sistema, por lo que esta API también proporciona soporte para devoluciones de llamada asíncronas. El proceso 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 la 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 esta forma los resultados de las tareas pueden asociarse mediante el ID. A continuación, comprenderemos cómo operar específicamente a través de un ejemplo. En primer lugar, la devolución de llamada Webhook es un servicio que puede recibir solicitudes HTTP, y los desarrolladores deben reemplazarla por la URL de un servidor HTTP creado por ellos mismos. Para facilitar la demostración, aquí se utiliza un sitio web público de ejemplo de Webhook https://webhook.site/; al abrir este sitio web se puede obtener una URL de Webhook, como se muestra en la imagen:

Copie esta URL para poder utilizarla 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 anterior, al mismo tiempo que se rellenan los parámetros correspondientes; el contenido específico se muestra en la imagen:

Haga clic en ejecutar y podrá observar que se obtiene inmediatamente un resultado, como se muestra a continuación:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Espere un momento y podremos 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:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}

Se puede ver que hay un campo task_id en el resultado; los demás campos son similares a los descritos anteriormente, y la asociación de tareas se puede realizar 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, ha 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 ha comprendido cómo utilizar Flux Images Generation API para generar imágenes mediante la introducción de palabras de indicación. 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

Coding

Más guías

Instrucciones de integración de la API de Generación de Imágenes Flux

Proceso de solicitud

Uso básico

Tarea de edición de imágenes

Devolución de llamada asíncrona

Manejo de errores

Ejemplo de respuesta de error

Conclusión

​Proceso de solicitud

​Uso básico

​Tarea de edición de imágenes

​Devolución de llamada asíncrona

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de solicitud

Uso básico

Tarea de edición de imágenes

Devolución de llamada asíncrona

Manejo de errores

Ejemplo de respuesta de error

Conclusión