JoyAI Image API

Documentación API

Genere y edite imágenes con una sola API pública. Use joyai para edición basada en instrucciones, o gptimage2 para text-to-image y edición con GPT Image 2.

Administrar claves API Inicio rápido

Resumen

Endpoint

/api/v1/generate

Un endpoint para modelos de imagen compatibles. Comportamiento con el campo model.

Auth

Claves API Bearer

Use una clave API del panel en el encabezado Authorization. Las claves del servidor nunca se envían al navegador.

Async

Resultados por tarea

La generación devuelve un task ID. Consulte status para las URL finales.

Autenticación

Cada solicitud requiere una clave API en el encabezado Authorization . Cree o rote claves desde Panel > Claves API.

Encabezado

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Modelos y créditos

model	Ideal para	Entrada de imagen requerida	Créditos
`joyai`	Edición por instrucciones con 1 a 3 imágenes de referencia.	Sí, 1 a 3 URL de imágenes.	24 créditos por solicitud.
`gptimage2`	Text-to-image y edición con GPT Image 2.	Opcional. Agregue imágenes para modo edición.	Text: 2/4/6 low, 12/24/36 medium, 44/88/132 high para 1k/2k/4k. Edit: 6/12/18 low, 12/24/36 medium, 44/88/132 high para 1k/2k/4k.

Inicio rápido

Envíe una solicitud a POST /api/v1/generate. La API devuelve un task ID de inmediato; use GET /api/v1/status para consultar hasta éxito o fallo.

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

Crea una tarea de generación o edición de imagen. Cuerpo JSON.

Parámetros de solicitud

Nombre	Tipo	Requerido	Descripción
`model`	string	Sí	Use joyai o gptimage2.
`prompt`	string	Sí	Instrucción en lenguaje natural. joyai hasta 1500 caracteres; gptimage2 hasta 20000.
`images`	string[]	Requerido para joyai; opcional para gptimage2	URL de imágenes. joyai acepta 1 a 3; gptimage2 entra en modo edición con imágenes.
`size`	string	Opcional para joyai	Tamaño como 10241024. Predeterminado 10241024.
`quality`	string	Opcional para gptimage2	low, medium o high. Predeterminado medium.
`resolution`	string	Opcional para gptimage2	1k, 2k o 4k. Predeterminado 1k.
`aspect_ratio`	string	Opcional para gptimage2	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 o 21:9.
`output_format`	string	Opcional para gptimage2	png, jpeg o webp. Predeterminado png.
`callback_url`	string	Opcional	URL almacenable con la tarea para flujos de callback.

Ejemplo JoyAI Edit

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

Ejemplo GPT Image 2

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

Respuesta

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

Consulte el estado con el task ID de /api/v1/generate. El parámetro model es opcional; los task ID se enrutan automáticamente cuando es posible.

cURL

curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

Errores

Los errores usan el mismo formato que las respuestas exitosas. Las respuestas públicas no exponen nombres internos de proveedores, workers o enrutamiento.

JSON

{
  "code": 400,
  "message": "prompt is required",
  "data": null
}

Estado	Significado
`400`	Parámetros faltantes o inválidos.
`401`	Clave API faltante o inválida.
`402`	Créditos insuficientes.
`500`	Error del servicio o servidor. Contacte soporte si se repite.