Core Endpoint

POST /api/v1/requests

Submit asynchronous work to Cannon Studio. Every operation enters through this endpoint.

Minimum request

Every API job uses the same envelope: an operation and an input object. Add webhook_url later if you want push updates.

{
  "operation": "prompt.enhance.video",
  "input": {
    "prompt": "A runner sprinting through a desert canyon at sunrise.",
    "visualStyle": "cinematic, high-contrast golden light",
    "duration": 8,
    "aspectRatio": "16:9",
    "rewriteRequest": "Make the camera motion feel premium but keep the direction readable."
  }
}

Curl example

curl -X POST https://www.cannonstudio.app/api/v1/requests \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CANNON_API_KEY" \
  -H "x-idempotency-key: quickstart-001" \
  -d '{
  "operation": "prompt.enhance.video",
  "input": {
    "prompt": "A runner sprinting through a desert canyon at sunrise.",
    "visualStyle": "cinematic, high-contrast golden light",
    "duration": 8,
    "aspectRatio": "16:9",
    "rewriteRequest": "Make the camera motion feel premium but keep the direction readable."
  }
}'

Request body

{
  "operation": "image.generate",
  "webhook_url": "https://your-app.com/webhooks/cannon",
  "input": {
    "prompt": "A cinematic detective portrait in the rain.",
    "model": "seedream5",
    "aspect_ratio": "16:9"
  }
}

Behavior

Validates the requested operation and input payload.
Creates a request object immediately and returns `202 Accepted`.
Supports idempotent create behavior through `x-idempotency-key`.
Persists a request log for 7 days with submitted input and terminal output for API calls.

Accepted response

{
  "id": "req_123",
  "status": "queued",
  "operation": "image.generate",
  "poll_after_ms": 2000,
  "urls": {
    "get": "https://www.cannonstudio.app/api/v1/requests/req_123"
  }
}