# Procesa imágenes con la API de SocialCutter desde PHP
> Cliente de la API de SocialCutter en PHP con cURL y Guzzle: salud, plataformas, procesado por URL y fichero con CURLFile, lotes, historial, monedero y errores.
- URL: https://socialcutter.theboomer.dev/guias/php/
- Idioma: es
- Familia: api
- Actualizado: 2026-09-24
- Palabras clave: PHP, cURL, Guzzle, API, SocialCutter, CURLFile, API key
## Requisitos

PHP con la extensión **cURL** (viene de serie en la mayoría de instalaciones). Si prefieres Guzzle, instálalo con Composer:

```bash
composer require guzzlehttp/guzzle
export SOCIALCUTTER_API_URL="https://api.socialcutter.theboomer.dev"
export SOCIALCUTTER_API_KEY="sc_tu_clave"
```

La clave se crea en https://dash.socialcutter.theboomer.dev, en **Perfil → API keys**. Empieza por `sc_` y se muestra una sola vez. La referencia completa está en https://docs.socialcutter.theboomer.dev.

## Cliente mínimo con cURL

```php
<?php
$apiUrl = getenv('SOCIALCUTTER_API_URL') ?: 'https://api.socialcutter.theboomer.dev';
$apiKey = getenv('SOCIALCUTTER_API_KEY'); // nunca la escribas en el codigo

function apiCall(string $method, string $path, ?array $json = null, array $multipart = []): array
{
    global $apiUrl, $apiKey;
    $ch = curl_init($apiUrl . $path);
    $headers = ['X-API-Key: ' . $apiKey, 'Accept: application/json'];

    if ($json !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($json));
    } elseif ($multipart) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $multipart); // cURL pone el boundary
    }

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 60,
    ]);

    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($body === false) {
        throw new RuntimeException('cURL: ' . curl_error($ch));
    }
    curl_close($ch);

    $data = json_decode($body, true);
    if ($status >= 400) {
        throw new RuntimeException("HTTP $status: $body");
    }
    return $data;
}
```

## Salud y credenciales

```php
// Publico: no requiere clave
print_r(apiCall('GET', '/api/v1/health'));   // status, version, uptime, database

// Identidad de la cuenta autenticada
print_r(apiCall('GET', '/api/v1/auth/me'));

// Usos disponibles
print_r(apiCall('GET', '/api/v1/credits'));
```

Si `/api/v1/auth/me` responde 401, la clave falta, está mal formada o fue revocada.

## Listar plataformas y formatos

```php
$data = apiCall('GET', '/api/v1/platforms');
foreach ($data['platforms'] as $plataforma => $formatos) {
    foreach ($formatos as $f) {
        echo "$plataforma {$f['format']} {$f['width']}x{$f['height']} {$f['aspect_ratio']}\n";
    }
}
```

`/platforms`, `/formats` y `/fit-modes` son públicos. Úsalos para construir los destinos sin codificar medidas a mano.

## Procesar una imagen por URL

```php
$resp = apiCall('POST', '/api/v1/images/process', [
    'source' => ['type' => 'url', 'value' => 'https://example.com/foto.jpg'],
    'destinations' => [
        ['platform' => 'instagram', 'format' => 'post'],
        ['platform' => 'tiktok', 'format' => 'cover'],
    ],
]);
echo $resp['id'], ' ', $resp['status'], "\n";
```

## Procesar un fichero local con CURLFile

```php
$resp = apiCall('POST', '/api/v1/images/process/upload', null, [
    'file' => new CURLFile('./foto.jpg', 'image/jpeg', 'foto.jpg'),
    'destinations' => json_encode([['platform' => 'linkedin', 'format' => 'post']]),
]);
```

Con `CURLFile` no fijes `Content-Type` a mano: cURL genera el `boundary` del multipart. El fichero va en el campo `file` y `destinations` es una cadena JSON. El límite de subida es 5 MB; por encima la API responde 413.

## Procesar un lote

```php
$lote = apiCall('POST', '/api/v1/images/batch', [
    'images' => [
        ['source' => ['type' => 'url', 'value' => 'https://example.com/a.jpg'],
         'destinations' => [['platform' => 'instagram', 'format' => 'post']]],
        ['source' => ['type' => 'url', 'value' => 'https://example.com/b.jpg'],
         'destinations' => [['platform' => 'twitter', 'format' => 'post']]],
    ],
]);
```

## Lo mismo con Guzzle

Guzzle simplifica el manejo de errores y el multipart:

```php
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => getenv('SOCIALCUTTER_API_URL') . '/',
    'headers'  => ['X-API-Key' => getenv('SOCIALCUTTER_API_KEY')],
    'timeout'  => 60,
]);

// Por URL
$resp = $client->post('api/v1/images/process', [
    'json' => [
        'source' => ['type' => 'url', 'value' => 'https://example.com/foto.jpg'],
        'destinations' => [['platform' => 'instagram', 'format' => 'post']],
    ],
])->json();

// Fichero local (multipart)
$resp = $client->post('api/v1/images/process/upload', [
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('./foto.jpg', 'r'), 'filename' => 'foto.jpg'],
        ['name' => 'destinations', 'contents' => json_encode([['platform' => 'linkedin', 'format' => 'post']])],
    ],
])->json();
```

En Guzzle, `json` envía el cuerpo JSON y `multipart` arma el formulario. Patrón documentado en https://docs.guzzlephp.org/en/stable/request-options.html; las opciones y nombres pueden cambiar entre versiones, confírmalos en esa documentación.

## Leer la respuesta y descargar

La respuesta trae el identificador del trabajo en `id`, un `status` y `outputs`, una entrada por destino con `platform`, `format`, `url`, `width`, `height` y `size_bytes`.

```php
foreach ($resp['outputs'] as $out) {
    echo "{$out['platform']} {$out['format']} {$out['width']}x{$out['height']}\n";
    $bytes = file_get_contents($out['url']);
    file_put_contents("{$out['platform']}-{$out['format']}.webp", $bytes);
}
```

## Historial y monedero

```php
// Ultimas 10 imagenes
print_r(apiCall('GET', '/api/v1/history?limit=10'));

// Solo las creadas desde la API
print_r(apiCall('GET', '/api/v1/history?origin=api&limit=10'));

// Cuota diaria, bolsa extra y saldo comprado
print_r(apiCall('GET', '/api/v1/wallet'));
```

`limit` admite de 1 a 100 y `skip` sirve para paginar. El filtro `origin` distingue `browser` (dashboard) de `api`.

## Errores y reintentos con backoff

```php
function conReintentos(callable $fn, int $intentos = 4, int $baseMs = 500)
{
    for ($i = 0; $i < $intentos; $i++) {
        try {
            return $fn();
        } catch (RuntimeException $e) {
            preg_match('/HTTP (\d+)/', $e->getMessage(), $m);
            $code = (int) ($m[1] ?? 0);
            if (($code === 429 || $code >= 500) && $i < $intentos - 1) {
                usleep($baseMs * 1000 * (2 ** $i)); // 0.5, 1, 2, 4 s
                continue;
            }
            throw $e;
        }
    }
}
```

No reintentes 400, 401, 404 o 422: repetir la misma petición no la arregla. Solo 429 (cuota) y 5xx (fallo temporal) merecen otro intento.

## Coste

- 1 uso por destino (plataforma y formato) por petición.
- Destinos repetidos en la misma petición no se cobran dos veces.
- Los procesamientos fallidos se devuelven.

## Errores típicos

| Código | Significado |
|---|---|
| 400 | Payload inválido: plataforma, formato o modo desconocido, JSON mal formado, o clave ya activa |
| 401 | Credenciales ausentes, mal formadas, caducadas o revocadas |
| 404 | Recurso no encontrado (id de imagen o de fichero) |
| 413 | El fichero supera 5 MB |
| 422 | Error de validación de la petición |
| 429 | Cuota del monedero agotada |
| 500 | Fallo de procesamiento; los usos de esa petición se devuelven |

## Siguientes pasos

- Guía de terminal: [Procesa imágenes con la API desde la terminal (curl)](/guias/curl/)
- Guía de Python: [Procesa imágenes con la API de SocialCutter desde Python](/guias/python/)
- Guía de Node: [Procesa imágenes con la API de SocialCutter desde Node.js](/guias/node/)
- Documentación de la API: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev