Documentación de la API: API de subida de imágenes

1. Descripción general de la API

Esta API se utiliza para subir archivos de imagen locales al servidor de alojamiento de imágenes del sistema. Tras una subida exitosa, generalmente devuelve un enlace de acceso en línea (URL) para la imagen.

• Estado actual: ?? En desarrollo

2. Detalles de la API

• Método HTTP: POST
• Endpoint: https://api.codingplanx.ai/api/upload
• Content-Type: multipart/form-data

3. Parámetros de la solicitud

3.1 Encabezados de la solicitud

3.2 Cuerpo de la solicitud

Esta API utiliza el formato multipart/form-data para transmitir datos. Los campos específicos son los siguientes:

4. Parámetros de respuesta

4.1 Estado de respuesta

• Código de estado HTTP: 200 OK
• Content-Type: application/json

4.2 Estructura de datos de respuesta

Los campos específicos para el modelo de respuesta aún no están definidos (el Schema es un objeto vacío {}). A continuación se muestra un ejemplo general de respuesta exitosa:

{
  "code": 200,
  "message": "Éxito"
}

(Nota: Una vez finalizado el desarrollo, este objeto JSON normalmente incluirá la URL de la imagen, por ejemplo, "url": "https://...")

---

5. Ejemplos de código de solicitud

Para facilitar una integración rápida, a continuación se muestran ejemplos de llamadas en tres lenguajes/herramientas comunes:

5.1 cURL

curl --location --request POST 'https://api.codingplanx.ai/api/upload' \
--form 'file=@"/C:/Users/Administrator/Desktop/d63ea1bd9011777e653b1addc7a88433.png"'

5.2 Python (Requests)

import requests

url = "https://api.codingplanx.ai/api/upload"

payload={}
files=[
  ('file',('image.png',open('C:/Users/Administrator/Desktop/d63ea1bd9011777e653b1addc7a88433.png','rb'),'image/png'))
]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

5.3 JavaScript (Fetch API)

const myHeaders = new Headers();

const formdata = new FormData();
// Suponiendo que fileInput es el elemento <input type="file"> en tu HTML
formdata.append("file", fileInput.files[0], "d63ea1bd9011777e653b1addc7a88433.png");

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: formdata,
  redirect: 'follow'
};

fetch("https://api.codingplanx.ai/api/upload", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

---

6. Preguntas frecuentes (FAQs)

P1: ¿Qué formatos de imagen son compatibles para la subida?

R: Generalmente, la API de alojamiento de imágenes admite formatos de imagen convencionales como JPG, JPEG, PNG, GIF y WebP. Se recomienda asegurarse de que la extensión del archivo y el tipo MIME sean correctos al realizar una solicitud. Las restricciones específicas están sujetas a las reglas de validación reales del backend.

P2: ¿Existe un límite de tamaño de archivo para la subida de imágenes?

R: Sí. Aunque actualmente no se indica en la documentación, para garantizar la estabilidad del servidor, generalmente existen límites de tamaño en los archivos subidos (por ejemplo, no más de 5 MB o 10 MB por imagen). Si sube un archivo demasiado grande, es posible que reciba un error de código de estado HTTP 413 Payload Too Large.

P3: ¿Por qué obtengo un error de CORS (origen cruzado) al llamar desde el frontend?

R: Esto sucede porque el dominio de tu página frontend no coincide con el dominio de la API (api.codingplanx.ai), lo que activa la Política del Mismo Origen del navegador. Por favor, comunícate con los desarrolladores del backend para configurar el encabezado de respuesta Access-Control-Allow-Origin correcto en el servidor, o utiliza un Proxy para la depuración del desarrollo frontend local.

P4: La documentación indica que el parámetro file "no es requerido". ¿Qué pasa si no lo envío?

R: En la definición actual de la API, file está marcado como required: false. Si omites este parámetro, la API seguirá devolviendo un código de estado 200 OK (según el diseño actual), pero no podrá completar realmente el proceso de almacenamiento de la imagen. Se recomienda encarecidamente incluir siempre el parámetro de archivo en tu lógica de negocio.

P5: ¿Cómo obtengo la URL de la imagen después de una subida exitosa?

R: La API se encuentra actualmente en estado de desarrollo (developing), y el esquema JSON devuelto está temporalmente vacío. Una vez finalizado el desarrollo, el equipo de desarrollo agregará campos de retorno (como url o data.link) al JSON del cuerpo de respuesta 200. Mantente atento a las futuras actualizaciones de la documentación de esta API.