API reference

Use these REST endpoints from Prompt Converter Cloud. Authenticate with a Cloud API key after you subscribe.

Authentication

Send Authorization: Bearer pc_cloud_… or the X-Api-Key header. Create keys on the API keys page after an active Cloud subscription. Do not send a Supabase JWT to these endpoints.

Base URL

Production uses your Cloud host, for example https://api.yourdomain.com. Local development uses http://localhost:5000.

Errors

Failed requests return a JSON object with a machine-readable error code and an optional message.

{
  "error": "quota_exceeded",
  "message": "Optional human-readable detail"
}

Convert a prompt

POST /v1/convert

Converts raw text into an optimized prompt for the selected model. Available on every Cloud plan and counted against the monthly conversion quota.

Available on: All Cloud plans

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.
Content-Type string required: Must be application/json for JSON request bodies.

Body parameters

rawInput string required: The user text to convert or send as the chat turn.
targetModel string optional: Routing key: gpt, claude, gemini, or grok. Defaults to gpt.
openAiResultModel string optional: Optional OpenAI model id from GET /v1/models when targetModel is gpt.
claudeResultModel string optional: Optional Anthropic model id from GET /v1/models when targetModel is claude.
geminiResultModel string optional: Optional Gemini model id from GET /v1/models when targetModel is gemini.
grokResultModel string optional: Optional xAI Grok model id from GET /v1/models when targetModel is grok.

Example request

curl -X POST https://api.yourdomain.com/v1/convert \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"rawInput":"Explain dependency injection in .NET","targetModel":"gpt"}'

Success response

{
  "result": "You are a senior .NET architect...",
  "targetModel": "gpt",
  "resultModel": "gpt-5.6-luna"
}

Errors

400 raw_input_required, 401 missing_authorization / invalid_api_key, 403 subscription_required, 429 quota_exceeded, 502 provider_failed

Create a chat completion

POST /v1/chat

Runs a single-turn chat completion with the same model-selection fields as convert. Growth and Business only. Counts against the monthly conversion quota.

Available on: Growth and Business

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.
Content-Type string required: Must be application/json for JSON request bodies.

Body parameters

rawInput string required: The user text to convert or send as the chat turn.
targetModel string optional: Routing key: gpt, claude, gemini, or grok. Defaults to gpt.
openAiResultModel string optional: Optional OpenAI model id from GET /v1/models when targetModel is gpt.
claudeResultModel string optional: Optional Anthropic model id from GET /v1/models when targetModel is claude.
geminiResultModel string optional: Optional Gemini model id from GET /v1/models when targetModel is gemini.
grokResultModel string optional: Optional xAI Grok model id from GET /v1/models when targetModel is grok.

Example request

curl -X POST https://api.yourdomain.com/v1/chat \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"rawInput":"Explain dependency injection","targetModel":"gpt","openAiResultModel":"gpt-5.6-luna"}'

Success response

{
  "result": "Dependency injection is a technique...",
  "targetModel": "gpt",
  "resultModel": "gpt-5.6-luna"
}

Errors

400 raw_input_required, 401 missing_authorization / invalid_api_key, 403 plan_required, 429 quota_exceeded, 502 provider_failed

List models

GET /v1/models

Returns chat, image, and video models with short descriptions. Use id as *ResultModel or modelId in the other endpoints.

Available on: Growth and Business

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.

Query parameters

kind string optional: Optional filter: chat, image, or video.

Example request

curl https://api.yourdomain.com/v1/models?kind=chat \
  -H "Authorization: Bearer pc_cloud_..."

Success response

{
  "models": [
    {
      "id": "gpt-5.6-luna",
      "displayName": "GPT-5.6 Luna",
      "provider": "openai",
      "kind": "chat",
      "description": "Chat model",
      "targetModel": "gpt"
    }
  ]
}

Errors

401 missing_authorization / invalid_api_key, 403 plan_required, 502 internal_error

Generate images

POST /v1/images

Generates images synchronously and returns signed URLs. Growth includes 80 images per billing period; Business includes 300.

Available on: Growth and Business

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.
Content-Type string required: Must be application/json for JSON request bodies.

Body parameters

prompt string required: Generation prompt. Must be a non-empty string.
modelId string required: Model id from GET /v1/models for the matching kind.
aspectRatio string optional: Optional aspect ratio such as 1:1, 16:9, 9:16, or 4:3.
count integer optional: Optional image count (1–4) when the model allows more than one.
quality string optional: Optional OpenAI image quality: standard or high.

Example request

curl -X POST https://api.yourdomain.com/v1/images \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A red balloon over a lake at dusk","modelId":"gpt-image-2","aspectRatio":"16:9"}'

Success response

{
  "jobId": "11111111-1111-1111-1111-111111111111",
  "status": "completed",
  "kind": "image",
  "modelId": "gpt-image-2",
  "results": [
    {
      "storagePath": "user/job-0.png",
      "signedUrl": "https://...",
      "mimeType": "image/png"
    }
  ]
}

Errors

400 prompt_required / model_not_allowed, 401 missing_authorization, 403 plan_required, 429 quota_exceeded, 502 provider_failed

Generate a video

POST /v1/videos

Starts a video generation job and returns HTTP 202 with a jobId. Poll GET /v1/videos/{jobId} until completed or failed. Growth includes 20 videos per billing period; Business includes 50.

Available on: Growth and Business

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.
Content-Type string required: Must be application/json for JSON request bodies.

Body parameters

prompt string required: Generation prompt. Must be a non-empty string.
modelId string required: Model id from GET /v1/models for the matching kind.
aspectRatio string optional: Optional aspect ratio such as 1:1, 16:9, 9:16, or 4:3.
durationSeconds integer optional: Optional video duration in seconds when the model allows it (typically 4 or 8).

Example request

curl -X POST https://api.yourdomain.com/v1/videos \
  -H "Authorization: Bearer pc_cloud_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A red balloon drifting over a lake","modelId":"sora-2","aspectRatio":"16:9","durationSeconds":8}'

Success response

{
  "jobId": "22222222-2222-2222-2222-222222222222",
  "status": "processing",
  "kind": "video",
  "modelId": "sora-2"
}

Errors

400 prompt_required / model_not_allowed, 401 missing_authorization, 403 plan_required, 429 quota_exceeded, 502 provider_failed

Poll a video job

GET /v1/videos/{jobId}

Returns the current status of a video job owned by the API key user. Completed jobs include signed result URLs.

Available on: Growth and Business

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.

Path parameters

jobId uuid required: Job id returned by POST /v1/videos.

Example request

curl https://api.yourdomain.com/v1/videos/22222222-2222-2222-2222-222222222222 \
  -H "Authorization: Bearer pc_cloud_..."

Success response

{
  "jobId": "22222222-2222-2222-2222-222222222222",
  "status": "completed",
  "kind": "video",
  "modelId": "sora-2",
  "results": [
    {
      "storagePath": "user/job.mp4",
      "signedUrl": "https://...",
      "mimeType": "video/mp4"
    }
  ]
}

Errors

400 job_id_required, 401 missing_authorization, 403 plan_required, 404 job_not_found

Get usage

GET /v1/usage

Returns conversion and media usage for the current Cloud billing period, including plan limits.

Available on: All Cloud plans

Headers

Authorization string optional: Bearer pc_cloud_… Cloud API key. Required unless X-Api-Key is sent.
X-Api-Key string optional: pc_cloud_… Cloud API key. Alternative to the Authorization header.

Example request

curl https://api.yourdomain.com/v1/usage \
  -H "Authorization: Bearer pc_cloud_..."

Success response

{
  "used": 42,
  "limit": 5000,
  "planName": "growth",
  "periodStart": "2026-07-01T00:00:00Z",
  "periodEnd": "2026-08-01T00:00:00Z",
  "imagesUsed": 3,
  "imagesLimit": 80,
  "videosUsed": 1,
  "videosLimit": 20
}

Errors

401 missing_authorization / invalid_api_key, 502 internal_error

Health check

GET /v1/health

Liveness probe. Does not require an API key.

Available on: Public (no API key)

Example request

curl https://api.yourdomain.com/v1/health

Success response

{ "status": "ok" }

Errors

—