Skip to main content
POST

Autorización

string
requerido
Todos los endpoints de la API requieren autenticación mediante Bearer TokenObtenga su clave de API:Visite la página de gestión de claves de API para obtener su clave de APIAñádala a la cabecera de la solicitud:
Modelo de imagen única: seedream-5-0-pro genera solo 1 imagen por solicitud (excepto en la descomposición por capas). Los siguientes parámetros se rechazan (HTTP 400, sin tarea ni cobro):
  • n > 1
  • sequential_image_generation (no se admite la generación en grupo)
  • stream (no se admite streaming)
  • tools (no se admite la búsqueda web)
  • más de 10 elementos en image_urls

Edición interactiva

Use coordenadas <point> / <bbox> en el prompt o cargue una imagen con anotaciones dibujadas a mano para ubicar las ediciones con precisión.
  • Coordenadas de punto: <point>x y</point> (especifican un solo punto; el modelo determina el área afectada)
  • Coordenadas de cuadro delimitador: <bbox>x1 y1 x2 y2</bbox> (especifican las coordenadas superior izquierda e inferior derecha para controlar con precisión el tamaño del área de edición)

Descomposición por capas

Separe una imagen en una imagen base y hasta 16 capas PNG transparentes, con información de posición y orden de apilamiento.

Cuerpo de la solicitud

string
predeterminado:"seedream-5-0-pro"
requerido
Nombre del modelo de generación de imágenes
  • seedream-5-0-pro (recomendado)
  • También se acepta: seedream-5.0-pro
boolean
predeterminado:"false"
Indica si se debe moderar el contenido antes de enviar la tarea de imagen.
  • true: revisar los prompts y las imágenes de entrada con omni-moderation-latest
  • false u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)
string
requerido
Descripción textual para la generación de la imagenEs opcional cuando layer_decomposition: true; si se omite, el modelo identifica y separa automáticamente los elementos principales de la imagen.Además de chino e inglés, la generación nativa de texto admite ruso, árabe, filipino, tailandés, turco, coreano, malayo, español, portugués, indonesio, francés, alemán, vietnamita y japonés.
Consejo: manténgala en menos de 600 palabras en inglés; una descripción demasiado larga puede perder detalle.
string
predeterminado:"1K"
Nivel de resolución (se aceptan minúsculas). Es una extensión de API Mart equivalente a indicar el nivel directamente en size.
  • 1K (predeterminado)
  • 1.5K (mismo precio que 1K, mejor calidad — prefiera 1.5K salvo motivo en contra)
  • 2K
Niveles no admitidos como 3K / 4K devuelven 400.Si se proporcionan size como nivel y resolution, prevalece size.
Cuando size es un valor de píxel exacto (p. ej. 2048x1024), este campo se ignora y las dimensiones salen solo de size.
string
predeterminado:"auto"
Una palabra clave de nivel, una relación de aspecto, auto o dimensiones exactas en píxeles.

Forma ①: nivel de resolución (recomendado)

El nivel puede indicarse directamente en size o mediante el campo de extensión de API Mart resolution:
Ambas formas son equivalentes. Si solo se especifica un nivel, describa el diseño deseado en el prompt (por ejemplo, “cartel vertical” o “portada horizontal”) y deje que el modelo elija la relación de aspecto.

Forma ②: nivel + relación de aspecto

Se usa con resolution. Proporciones admitidas:
  • 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 2:1, 1:2, 21:9
  • También acepta separador x estilo 16x9
  • 2x1 equivale a 2:1 y 1x2 equivale a 1:2. La x debe escribirse en minúscula y no se admiten espacios.
  • auto (predeterminado): solo el nivel de resolución; la proporción final se elige según el prompt / las referencias
Proporciones fuera de la lista (p. ej. 9:21) devuelven 400 — sin fallback silencioso a 1:1.Nivel × proporción → píxeles de salida:

Forma ③: píxeles exactos

Cuando size es widthxheight, los píxeles se usan tal cual y resolution no aplica. Acepta 2048X1024 / 2048×1024.
Los límites se aplican al producto de ancho y alto, no a cada lado por separado. Ejemplo: 512×512 es demasiado pequeño (400); 2048×1024 es válido.
string
predeterminado:"opaque"
Modo de fondo de salida:
  • opaque: fondo opaco (predeterminado)
  • transparent: fondo transparente
transparent solo está disponible para solicitudes de imagen a imagen con exactamente una imagen de entrada que ya tenga canal alfa; también se requiere output_format: "png".
boolean
predeterminado:"false"
Indica si se descompone la imagen en capas. Al activarlo, el modelo devuelve una imagen base y hasta 16 capas PNG con canal alfa.Se requiere exactamente una imagen PNG o JPEG. Debe contener entre [262144, 36000000] píxeles totales y no superar 30 MB. size solo acepta 1K, 1.5K, 2K o auto, y su valor predeterminado es auto. output_format solo controla el formato de la imagen base; las capas descompuestas siempre son PNG.
object
predeterminado:"{\"mode\":\"standard\"}"
Modo de optimización del prompt:
  • standard: modo estándar con mejor calidad (predeterminado)
También se acepta la forma plana "optimize_prompt_options.mode": "standard".
integer
predeterminado:"1"
Número de imágenes que se generarán. Solo se admite 1; use seedream-5-0-lite para generar grupos de imágenes.
array
Lista de URL de imágenes de referencia para image-to-image con una / varias referencias, hasta 10Dos formatos:1. URL pública
  • http:// o https://
  • Ejemplo: https://example.com/image.jpg
2. Base64 (Data URI)
  • Formato: data:image/<format>;base64,<data><format> debe ir en minúsculas
  • Ejemplo: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...
Límites por imagen:
  • Formatos: jpeg / png / webp / bmp / tiff / gif / heic / heif
  • Proporción (a/al): [1/16, 16]
  • Cada lado > 14 px
  • Tamaño ≤ 30 MB
  • Píxeles totales ≤ 6000×6000 (36.000.000)
Facturación: la primera imagen de referencia es gratuita; cada imagen adicional tiene un recargo fijo.
string
predeterminado:"jpeg"
Formato de salida de la imagen
  • jpeg (predeterminado)
  • png
Compatibilidad: response_format equivale a output_format; otros valores se tratan como jpeg.
boolean
predeterminado:"false"
Si se añade una marca de agua “AI generated” en la esquina inferior derecha
  • true: añadir marca de agua
  • false: sin marca de agua (predeterminado)

Ejemplos de solicitud

Text-to-image (nivel + proporción)

Text-to-image (píxeles exactos)

Multi-referencia

Recomendado: 1.5K mismo precio, mejor calidad

Descomposición por capas

También puede usar coordenadas <bbox> normalizadas a 0–1000 para identificar con precisión los elementos que desea extraer:

Edición interactiva

Describa con lenguaje natural las anotaciones dibujadas a mano en la imagen:
O indique ubicaciones precisas con <point> / <bbox>:

Edición del canal alfa

Ejemplo completo: enviar una tarea y obtener la imagen

El siguiente script muestra el flujo completo: enviar una tarea asíncrona, consultar su estado, gestionar los estados de error y leer la URL final de la imagen. Sustituya YOUR_API_KEY antes de ejecutarlo.
Python
Cuando se completa correctamente, el endpoint de consulta de tareas devuelve:
Las imágenes devueltas se replican en almacenamiento administrado por la plataforma. Aun así, descárguelas y guárdelas cuanto antes en su propio sistema; no trate la URL del resultado como almacenamiento permanente.

Escenarios completos con cURL

Composición de varias imágenes (hasta 10 referencias)

Píxeles exactos, optimización del prompt y marca de agua

Descomponer y editar una capa transparente por separado

Primero, descomponga la imagen de origen:
Después, obtenga la URL de una capa transparente y edítela por separado:

Respuesta y reconstrucción de la descomposición por capas

Los arrays url, sizes, output_formats y layers se corresponden por índice; el índice 0 siempre es la imagen base:
Componga las capas en orden ascendente de z_index. Para reconstruirlas sobre la imagen base de salida con coordenadas absolutas:
Para reconstruirlas sobre cualquier lienzo de W × H, use coordenadas normalizadas:
La descomposición por capas se factura por imagen. Al enviar la tarea se preautorizan hasta 17 imágenes. Al finalizar, cada salida se clasifica según su cantidad real de píxeles y se liquida por separado; cualquier exceso de preautorización se reembolsa automáticamente. El saldo debe cubrir la preautorización de 17 imágenes y size: "auto" se preautoriza en el nivel 2K.

Notas de facturación

La salida se tarifica por el total real de píxeles (~2.61M = 2,601,124):
  • 1.5K cuesta lo mismo que 1K ($0.045).
  • Con píxeles exactos en size, la facturación usa el área de salida real; resolution no influye (p. ej. size: "2048x2048" → $0.09).
  • La 1.ª imagen de referencia es gratis; cada una adicional tiene recargo.
  • Las tareas fallidas se reembolsan por completo.

Preautorización y liquidación de la descomposición por capas

Como al enviar la tarea no se conocen el número ni las dimensiones finales de las capas, la preautorización aplica reglas conservadoras basadas en la solicitud:
  • Píxeles exactos: nivel según el área de píxeles solicitada.
  • 1K / 1.5K: preautorizado en el nivel 1K.
  • 2K: preautorizado en el nivel 2K.
  • auto: puede generar hasta 2K, por lo que se preautoriza en el nivel 2K.
Al finalizar, la imagen base y cada capa real se clasifican y suman individualmente según su área real de píxeles. El exceso de preautorización se reembolsa automáticamente. Las capas suelen ser mucho menores que la imagen base, por lo que incluso una tarea preautorizada en 2K puede liquidarse por completo en el nivel 1K.
Ejemplo: una entrada de 1080×1080 se descompone en 10 imágenes. La tarea se preautoriza como 17 imágenes × nivel 2K. Si las 10 imágenes finales no superan 2,61 millones de píxeles, se liquida como 10 imágenes × nivel 1K y el crédito restante se reembolsa automáticamente.

Errores comunes

⏱️ Generación más lenta: ~90 s para 1K y ~160 s para 2K (prioridad a la calidad). Consulte Obtener estado de la tarea cada 5–10 segundos y configure el tiempo de espera del cliente en 5 minutos. Guarde los resultados generados cuanto antes.

Respuesta

integer
Código de estado de la respuesta
array
Array de datos de la respuesta