Referencia de API
Seedream Texto a imagen
Usa el endpoint de texto a imagen para crear una tarea asíncrona.
01
Descripción general
Usa el endpoint de texto a imagen con un modelo compatible. Usa el ID de tarea devuelto para recuperar su estado, o proporciona callback_url para las entregas documentadas a continuación.
Inicio rápido
- Cree una Clave de API y establézcala como RUNAPI_API_KEY.
- Elija un modelo compatible y envíe una solicitud POST cuyo cuerpo coincida con el esquema de ese modelo.
- Almacena el ID de tarea devuelto, luego sondea hasta alcanzar un estado terminal o gestiona las devoluciones de llamada documentadas a continuación.
Endpoint
- URL base
https://runapi.ai- Versión de la API
v1- Autenticación
Authorization: Bearer YOUR_API_TOKEN
02
Modelos compatibles
Abra una página de modelo para conocer los precios actuales, los límites de velocidad y los detalles de uso comercial.
03
Cuerpo JSONEsquema de solicitud
Los campos y los valores permitidos dependen del modelo seleccionado. Cuando se proporciona, callback_url recibe las entregas de tareas documentadas a continuación.
seedream-4.5-text-to-image9 campos
aspect_ratiostring
Obligatorio
Valores permitidos:
1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
callback_urlstring
Opcional
enable_safety_checkerboolean
Opcional
modelstring
Opcional
output_countinteger
Opcional
output_qualitystring
Obligatorio
Valores permitidos:
basic, high
output_resolutionstring
Opcional
promptstring
Opcional
seedinteger
Opcional
seedream-5-lite-text-to-image10 campos
aspect_ratiostring
Obligatorio
Valores permitidos:
1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
callback_urlstring
Opcional
enable_safety_checkerboolean
Opcional
modelstring
Opcional
output_countinteger
Opcional
output_formatstring
Opcional
Valores permitidos:
png, jpeg
Valor predeterminado: png
output_qualitystring
Obligatorio
Valores permitidos:
basic, high, ultra
output_resolutionstring
Opcional
promptstring
Opcional
seedinteger
Opcional
seedream-5-pro-text-to-image7 campos
aspect_ratiostring
Obligatorio
Valores permitidos:
1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
callback_urlstring
Opcional
enable_safety_checkerboolean
Opcional
modelstring
Opcional
output_formatstring
Opcional
Valores permitidos:
png, jpeg
Valor predeterminado: png
output_qualitystring
Obligatorio
Valores permitidos:
basic, high
promptstring
Obligatorio
Rango:
3 - 5000
seedream-v4-text-to-image9 campos
aspect_ratiostring
Opcional
Valores permitidos:
1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9
callback_urlstring
Opcional
enable_safety_checkerboolean
Opcional
modelstring
Opcional
output_countinteger
Opcional
Valores permitidos:
1, 2, 3, 4, 5, 6
output_qualitystring
Opcional
output_resolutionstring
Opcional
Valores permitidos:
1k, 2k, 4k
promptstring
Opcional
seedinteger
Opcional
Reglas condicionales
Estos requisitos se aplican cuando todas las condiciones enumeradas coinciden.
-
Cuando
model = seedream-4.5-text-to-image- Obligatorio
- No aceptado
output_format
-
Cuando
model = seedream-5-pro-text-to-image- Obligatorio
- No aceptado
output_resolution,output_count,seed
-
Cuando
model = seedream-v4-text-to-image- Obligatorio
- No aceptado
output_format
04
HTTP 202Crear aceptación
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200Consulta en proceso
GET /api/v1/seedream/text_to_image/:id
Esquema de respuesta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200Consulta completada
GET /api/v1/seedream/text_to_image/:id
Esquema de respuesta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"images": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"images",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"images": [
{
"url": "https://cdn.runapi.ai/public/samples/image.jpg"
}
],
"status": "completed"
}07
HTTP 200Consulta fallida
GET /api/v1/seedream/text_to_image/:id
Esquema de respuesta
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200Devolución de llamada del cliente: completado
POST callback_url
Esquema de respuesta
JSON
{
"properties": {
"id": {
"type": "string"
},
"images": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"images"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"id": "tsk_reference_demo",
"images": [
{
"url": "https://cdn.runapi.ai/public/samples/image.jpg"
}
],
"status": "completed"
}09
HTTP 200Devolución de llamada del cliente: fallido
POST callback_url
Esquema de respuesta
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "Authentication required"
}11
HTTP 401Errores
GET /api/v1/seedream/text_to_image/:id
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "Authentication required"
}12
HTTP 400Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Resumen de validación legible por personas.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}Ejemplo de respuesta
JSON
{
"error": "model must be one of: seedream-4.5-text-to-image, seedream-5-lite-text-to-image, seedream-5-pro-text-to-image, seedream-v4-text-to-image"
}13
HTTP 402Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "Insufficient balance"
}14
HTTP 429Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504Errores
POST /api/v1/seedream/text_to_image
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "The request timed out"
}19
HTTP 404Errores
GET /api/v1/seedream/text_to_image/:id
Esquema de respuesta
JSON
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Ejemplo de respuesta
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
Ejemplos de código generados
Usa cURL directamente o instala un SDK para tu lenguaje. Cada muestra envía la solicitud validada que se muestra en esta referencia.
Instalar
Shell
pip install runapi-seedream
PYTHON
import os
from runapi.seedream import SeedreamClient
client = SeedreamClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_image.create(
model="seedream-5-pro-text-to-image",
prompt="A cobalt vase on white marble.",
aspect_ratio="1:1",
output_quality="high"
)