A good place to start.

Your first request

Sign in, open Account → API access and reveal your key. Store it in an environment variable. Load the model catalog to choose a real modelId, then submit your request.

curl 'https://framelyn.tcmzhan.com/api/open/v1/generations' \
  -H "Authorization: Bearer $FRAMELYN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "handler": "text_to_image",
  "modelId": "YOUR_MODEL_ID",
  "clientRequestId": "your-unique-request-id",
  "input": {
    "prompt": "A sculptural house on a quiet coast, golden hour."
  }
}'

The service returns a JSON envelope with success, code, message and data. A successful create returns the task in data.

Authentication

Use your account API key in the Authorization header. Your studio login token is a different credential and should not be used for the public API.

Authorization: Bearer YOUR_API_KEY

Keep keys on your server. Do not ship them in public browser bundles. Disable or replace a key in Account if you need to revoke access; replacement immediately invalidates the previous key.

Models & capabilities

The catalog returns models your API key can use. Choose data[].modelId for generation. Model type, supportedHandlers and config describe available modalities, generation modes and output settings. Config may be a JSON string; parse it before reading settings.

Retrieve available handler names. Text models use the chat gateway; they cannot be submitted to the media generation endpoint.

Creating media

{
  "handler": "text_to_image",
  "modelId": "YOUR_MODEL_ID",
  "clientRequestId": "your-unique-request-id",
  "input": {
    "prompt": "A sculptural house on a quiet coast, golden hour."
  }
}

handler, modelId and input determine the task. Always include a unique clientRequestId for a new request. The same ID and unchanged parameters retrieve the original task, which protects retries from duplicate billing.

Reference-driven video

{
  "handler": "image_to_video",
  "modelId": "YOUR_VIDEO_MODEL",
  "clientRequestId": "another-unique-id",
  "input": {
    "prompt": "The camera moves slowly through the scene.",
    "imageUrl": "https://your-public-asset.example/reference.jpg",
    "duration": 5
  }
}

Video enhancement

Enhancement uses an owned source video and a priced output tier. RH Upscale also accepts enhancement levels and interpolation. Do not include a prompt.

{
  "handler": "video_upscale",
  "modelId": "rh-upscale",
  "clientRequestId": "unique-upscale-id",
  "input": {
    "videoUrl": "https://your-uploaded-video.example/input.mp4",
    "targetResolution": "4k",
    "upscaleModel": "max",
    "outputFps": "2x"
  }
}

Request a quote with modelId, videoUrl, targetResolution and the optional RH upscaleModel. The server verifies ownership and source duration. A quote is an estimate; generation rechecks it before charging.

Tasks & results

Poll the task ID returned by create. Status values are 0 processing, 1 succeeded, 2 failed and 3 cancelled. Use resultUrl for the primary output; additional output files may appear in resultMeta.urls.

{
  "success": true,
  "code": 200,
  "data": {
    "id": "TASK_ID",
    "status": 1,
    "progress": 100,
    "resultUrl": "https://your-result.example/output.png",
    "pointCost": 10
  }
}

Task IDs are strings. Preserve them as strings to avoid losing precision. Only the key owner can retrieve their tasks. A network timeout does not mean the task stopped.

Reference assets

Upload through your signed-in Library or Studio, then use the stored public URL in your request. API keys do not grant access to the login-only file management routes.

Images use imageList for editing. Image-to-video uses imageUrl; first/last-frame video uses imageList with two entries. Reference video can use imageUrls, videoReferences and audioReferences. Keep source URLs available throughout processing and follow each model's count and file size limits.

Chat & Responses

The same API key also authenticates the separate OpenAI-compatible namespace:

{
  "model": "YOUR_CHAT_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "Help me shape an idea for a short film."
    }
  ],
  "stream": false
}

Chat is token-metered. The service may reserve a credit ceiling before processing, then settle against actual usage and release unused credits. Follow these calls in Usage & credits.

Credits & idempotency

The studio and API share one account balance, model availability and concurrency limits. Media tasks charge on acceptance; failures enter the service's refund process. Credit activity records charges and refunds.

Use a new request ID only for a genuinely new generation. If a create times out, repeat its existing ID and original parameters first. Reusing an ID with different parameters is rejected. Reusing a failed task's ID returns that failed record.

Handling errors

A JSON business error may be returned inside an envelope. Always check success and code, not just HTTP status.