CloudRelay-Code/cloudrelay-imagegen-skill

O que cloudrelay-imagegen-skill faz?

Habilidade de agente entre clientes para a API assíncrona de imagens do CloudRelay, criada para evitar o timeout de ~120s do Cloudflare em gerações de imagens longas e ensinar agentes sobre submissão de jobs, polling e tratamento de resultados.

Visão Geral

Esta habilidade adiciona suporte para a API assíncrona de geração de imagens do CloudRelay em agentes de IA. Em vez de esperar síncronamente por uma resposta (que pode exceder o limite de timeout do Cloudflare), os agentes podem:

• Submeter um job de geração de imagem e receber um jobId
• Fazer polling do status do job usando o jobId
• Recuperar o resultado quando o status for completed

Plataformas Suportadas

• Claude Code
• Cursor
• Codex

Como Usar

1. Configurar Variável de Ambiente

Certifique-se de que a variável de ambiente CLOUDRELAY_API_KEY está definida com sua chave de API do CloudRelay.

2. Submeter um Job

curl -X POST https://api.cloudrelay.com/v1/images/generations \
  -H "Authorization: Bearer $CLOUDRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion-xl",
    "prompt": "A beautiful sunset over mountains"
  }'

Resposta:

{
  "jobId": "job_abc123",
  "status": "queued"
}

3. Polling do Status do Job

curl -X GET https://api.cloudrelay.com/v1/images/jobs/job_abc123 \
  -H "Authorization: Bearer $CLOUDRELAY_API_KEY"

Resposta:

{
  "jobId": "job_abc123",
  "status": "processing",
  "progress": 45
}

Continue fazendo polling até que o status seja completed ou failed.

4. Recuperar Resultado

Quando o status for completed, a resposta incluirá os dados da imagem:

{
  "jobId": "job_abc123",
  "status": "completed",
  "result": {
    "url": "https://cdn.cloudrelay.com/images/job_abc123.png",
    "width": 1024,
    "height": 1024,
    "format": "png"
  }
}

Tratamento de Erros

• Timeout de Polling: Se o job não for concluído dentro de um período razoável (ex.: 5 minutos), o agente deve notificar o usuário e sugerir verificação manual.
• Job Falhou: Se o status for failed, a resposta conterá um campo error com detalhes.
• API Key Inválida: Certifique-se de que a CLOUDRELAY_API_KEY está configurada corretamente.

Boas Práticas

• Backoff Exponencial: Ao fazer polling, use backoff exponencial (ex.: 1s, 2s, 4s, 8s) para evitar sobrecarregar a API.
• Timeout Máximo: Defina um timeout máximo de 300 segundos para o polling.
• Logging: Registre o jobId e o status para depuração.

Exemplo de Uso com Agente

# Exemplo de como um agente pode usar esta habilidade
skill = CloudRelayImageGenSkill(api_key=os.getenv("CLOUDRELAY_API_KEY"))
job_id = skill.submit_job(prompt="A cat wearing a hat")
print(f"Job submitted: {job_id}")

result = skill.wait_for_completion(job_id, timeout=300)
if result["status"] == "completed":
    print(f"Image URL: {result['result']['url']}")
else:
    print(f"Job failed: {result.get('error')}")

Contribuição

Sinta-se à vontade para abrir issues ou pull requests neste repositório.