Documentação da API: API de Upload de Imagem

1. Visão Geral da API

Esta API é usada para fazer upload de arquivos de imagem locais para o servidor de hospedagem de imagens do sistema. Após um upload bem-sucedido, ela geralmente retorna um link de acesso online (URL) para a imagem.

Status Atual: ?? Em Desenvolvimento

2. Detalhes da API

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

3. Parâmetros da Requisição

3.1 Cabeçalhos da Requisição

Parâmetro	Obrigatório	Exemplo	Descrição
Content-Type	Sim	`multipart/form-data`	Declara o corpo da requisição como um formato de upload de arquivo de formulário.

3.2 Corpo da Requisição

Esta API usa o formato multipart/form-data para transmitir dados. Os campos específicos são os seguintes:

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
file	`file` (binário)	Não*	`C:\Users\...\d63ea1bd9011777e653b1addc7a88433.png`	O arquivo de imagem a ser enviado. (Nota: Embora marcado como não obrigatório na especificação, é praticamente obrigatório para que a lógica de negócios de upload real funcione.)

4. Parâmetros de Resposta

4.1 Status da Resposta

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

4.2 Estrutura de Dados da Resposta

Os campos específicos para o modelo de resposta ainda não estão definidos (O Schema é um objeto vazio {}). Abaixo está um exemplo geral de resposta de sucesso:

{
  "code": 200,
  "message": "Success"
}

(Nota: Assim que o desenvolvimento for concluído, este objeto JSON normalmente incluirá a URL da imagem, ex: "url": "https://...")

5. Exemplos de Código de Requisição

Para facilitar a integração rápida, abaixo estão exemplos de chamadas em três linguagens/ferramentas comuns:

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();
// Supondo que fileInput seja o elemento <input type="file"> no seu 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. Perguntas Frequentes (FAQs)

Q1: Quais formatos de imagem são suportados para upload?

R: Geralmente, a API de hospedagem de imagens suporta formatos convencionais como JPG, JPEG, PNG, GIF e WebP. Recomenda-se garantir que a extensão do arquivo e o tipo MIME estejam corretos ao fazer uma requisição. Restrições específicas estão sujeitas às regras reais de validação do backend.

Q2: Existe um limite de tamanho de arquivo para uploads de imagens?

R: Sim. Embora não esteja anotado atualmente na documentação, para garantir a estabilidade do servidor, geralmente existem limites de tamanho nos arquivos enviados (por exemplo, não mais que 5 MB ou 10 MB por imagem). Se você enviar um arquivo muito grande, poderá receber um erro de código de status HTTP 413 Payload Too Large.

Q3: Por que estou recebendo um erro CORS (Cross-Origin) ao chamar pelo frontend?

R: Isso acontece porque o domínio da sua página frontend não corresponde ao domínio da API (api.codingplanx.ai), acionando a Política de Mesma Origem (Same-Origin Policy) do navegador. Entre em contato com os desenvolvedores do backend para configurar o cabeçalho de resposta Access-Control-Allow-Origin correto no servidor, ou use um Proxy para depuração e desenvolvimento local do frontend.

Q4: A documentação afirma que o parâmetro file é "não obrigatório". O que acontece se eu não o enviar?

R: Na definição atual da API, file está marcado como required: false. Se você omitir este parâmetro, a API ainda retornará um código de status 200 OK (com base no design atual), mas não poderá concluir o processo real de armazenamento da imagem. É altamente recomendável sempre incluir o parâmetro de arquivo na sua lógica de negócios.

Q5: Como obtenho a URL da imagem após um upload bem-sucedido?

R: A API está atualmente no estado developing (em desenvolvimento), e o JSON Schema retornado está temporariamente vazio. Assim que o desenvolvimento for concluído, a equipe adicionará campos de retorno (como url ou data.link) no JSON do corpo da resposta 200. Fique atento a futuras atualizações nesta documentação da API.