API Reference

Complete endpoint reference for the Pro Clubs Studio Partner API. All endpoints are under the base URL:

https://api.proclubsstudio.com/v1

All requests require an X-API-Key header. See Authentication.

POST

/v1/images

Submit an image creation request. Processing is asynchronous — the endpoint returns immediately with a 202 Accepted status and an image_id you can use to poll for results or receive via webhook.

Required headers

Header	Description
`X-API-Key`	Your partner API key.
`Idempotency-Key`	Unique key to prevent duplicate processing. Scoped per partner.
`Content-Type`	Must be `application/json`.

Request body

{
  "type": "player_card",
  "player": {
    "external_id": "partner_player_123",
    "name": "Zethxr",
    "position": "ST",
    "number": 18,
    "skill_level": 88,
    "source_image_url": "https://partner-platform.com/uploads/player123.png"
  },
  "style": {
    "preset": "pro_clubs_card",
    "width": 1024,
    "height": 1280,
    "background_theme": "stadium_night"
  },
  "branding": {
    "club_badge_url": "https://partner-platform.com/assets/badges/club.png",
    "primary_color": "#00E5D1",
    "secondary_color": "#1A1A2E"
  },
  "metadata": {
    "partner_user_id": "user_789",
    "trace_token": "optional-debug-token"
  }
}

Validation requirements

Field	Type	Required	Description
`type`	`string`	Yes	Image type. Phase 1: "player_card" only.
`player.external_id`	`string`	Yes	Your unique identifier for this player. Max 255 chars.
`player.name`	`string`	Yes	Player display name. 1–100 characters.
`player.position`	`enum`	Yes	ST, CF, LW, RW, CAM, CM, CDM, LM, RM, LB, RB, CB, or GK.
`player.number`	`integer`	Yes	Jersey number, range 1–99.
`player.skill_level`	`integer`	Yes	Overall skill rating, range 1–99.
`player.source_image_url`	`string`	Yes	HTTPS URL to the player photo. Must be publicly accessible.
`style.preset`	`string`	Yes	Style preset. Phase 1: "pro_clubs_card" only.
`style.width`	`integer`	No	Output width in pixels. 512–2048. Default: 1024.
`style.height`	`integer`	No	Output height in pixels. 512–2048. Default: 1280.
`style.background_theme`	`string`	No	Background theme name. Freeform in Phase 1.
`branding.club_badge_url`	`string`	No	HTTPS URL to club badge image.
`branding.primary_color`	`string`	No	Primary brand colour. Hex format (#RRGGBB).
`branding.secondary_color`	`string`	No	Secondary brand colour. Hex format (#RRGGBB).
`metadata`	`object`	No	Flat key-value pairs. Max 10 keys, values max 256 chars each.

Example request

curl -X POST "https://api.proclubsstudio.com/v1/images" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Idempotency-Key: partner-player-123-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "player_card",
    "player": {
      "external_id": "partner_player_123",
      "name": "Zethxr",
      "position": "ST",
      "number": 18,
      "skill_level": 88,
      "source_image_url": "https://partner-platform.com/uploads/player123.png"
    },
    "style": {
      "preset": "pro_clubs_card",
      "width": 1024,
      "height": 1280,
      "background_theme": "stadium_night"
    },
    "branding": {
      "club_badge_url": "https://partner-platform.com/assets/badges/club.png",
      "primary_color": "#00E5D1",
      "secondary_color": "#1A1A2E"
    },
    "metadata": {
      "partner_user_id": "user_789",
      "trace_token": "optional-debug-token"
    }
  }'

Response 202 Accepted

{
  "success": true,
  "data": {
    "image_id": "img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1",
    "status": "processing",
    "poll_url": "/v1/images/img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1",
    "eta_seconds": 15,
    "created_at": "2026-02-19T11:30:00Z"
  },
  "error": null
}

Error responses

Status	Code	Description
400	INVALID_REQUEST	Validation failed — missing or malformed fields.
401	INVALID_API_KEY	API key is missing, invalid, or revoked.
402	INSUFFICIENT_CREDITS	Not enough credits to process this request (live keys only).
409	IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD	Same idempotency key sent with a different request body.
422	UNSUPPORTED_IMAGE_SOURCE	Source image URL is unreachable, unsupported format, or exceeds size limit.
429	RATE_LIMIT_EXCEEDED	Too many requests. Retry after the specified interval.

GET

/v1/images/:image_id

Retrieve the current status and result of an image request. Returns the image URL and metadata when processing is complete, progress information while processing, or failure details if generation failed.

Path parameters

Parameter	Type	Description
`image_id`	`string`	The image ID returned from the create request (`img_*`).

Example request

curl "https://api.proclubsstudio.com/v1/images/img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1" \
  -H "X-API-Key: sk_live_xxx"

Response while processing 200

The progress field ranges from 0.0 to 1.0. It may be null if progress is indeterminate. Treat it as a best-effort estimate.

{
  "success": true,
  "data": {
    "image_id": "img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1",
    "status": "processing",
    "progress": 0.6,
    "created_at": "2026-02-19T11:30:00Z",
    "updated_at": "2026-02-19T11:30:07Z"
  },
  "error": null
}

Response when completed 200

{
  "success": true,
  "data": {
    "image_id": "img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1",
    "status": "completed",
    "result": {
      "image_url": "https://cdn.proclubsstudio.com/partner/img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1.png",
      "width": 1024,
      "height": 1280,
      "content_type": "image/png",
      "expires_at": "2026-05-21T11:30:12Z"
    },
    "usage": {
      "credits_used": 1
    },
    "created_at": "2026-02-19T11:30:00Z",
    "completed_at": "2026-02-19T11:30:12Z"
  },
  "error": null
}

Response when failed 200

Failed image requests return 200 because the resource exists — the operation itself failed. The completed_at timestamp indicates when the request reached its terminal state.

{
  "success": true,
  "data": {
    "image_id": "img_01HSXYZ9Y5T8S5H0R9F3A2M7Q1",
    "status": "failed",
    "failure": {
      "code": "IMAGE_PROCESSING_FAILED",
      "message": "Unable to detect player in source image"
    },
    "created_at": "2026-02-19T11:30:00Z",
    "completed_at": "2026-02-19T11:30:08Z"
  },
  "error": null
}

If the image_id does not belong to your partner account (or does not exist), the API returns 404 IMAGE_NOT_FOUND.

GET

/v1/images

List image requests with optional filtering and cursor pagination.

Query parameters

Parameter	Required	Description
`status`	No	Filter by status (`processing`, `completed`, `failed`).
`limit`	No	Number of results to return. Default `20`, max `100`.
`after`	No	Cursor for pagination. Use the `next_cursor` value from a previous response.

Example request

curl "https://api.proclubsstudio.com/v1/images?status=completed&limit=20" \
  -H "X-API-Key: sk_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "images": [
      {
        "image_id": "img_01HS...",
        "status": "completed",
        "type": "player_card",
        "created_at": "2026-02-19T11:30:00Z",
        "completed_at": "2026-02-19T11:30:12Z"
      }
    ],
    "has_more": true,
    "next_cursor": "img_01HS..."
  },
  "error": null
}

When has_more is true, pass the next_cursor value as the after query parameter to fetch the next page.

GET

/v1/usage

Retrieve usage statistics and credit information for your partner account. Results are scoped to the environment of the API key used (live or test).

Query parameters

Parameter	Required	Values	Description
`period`	Yes	`current_month`, `previous_month`, `last_30_days`	The time period to aggregate usage for.

Example request

curl "https://api.proclubsstudio.com/v1/usage?period=current_month" \
  -H "X-API-Key: sk_live_xxx"

Response 200

{
  "success": true,
  "data": {
    "period": "2026-02",
    "images_requested": 1247,
    "images_completed": 1221,
    "images_failed": 26,
    "credits_used": 1221,
    "credits_remaining": 8779,
    "credit_limit": 10000,
    "environment": "live"
  },
  "error": null
}

Response fields

Field	Type	Description
`period`	`string`	The billing period (e.g. "2026-02").
`images_requested`	`integer`	Total image requests submitted in the period.
`images_completed`	`integer`	Images that completed successfully.
`images_failed`	`integer`	Images that failed processing.
`credits_used`	`integer`	Credits consumed this period.
`credits_remaining`	`integer`	Available credits in your account.
`credit_limit`	`integer`	Total credit allocation for your plan.
`environment`	`string`	"live" or "test", based on the key used.

Common response headers

All API responses include these headers:

Header	Description
`X-Request-Id`	Unique request trace ID for debugging and support.
`X-RateLimit-Limit`	Maximum requests allowed per minute for your tier.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets.
`Retry-After`	Seconds until reset. Only present on `429` responses.