This guide covers the full technical integration for external services connecting to the Creative Force Cloud Automation API. It picks up where your Creative Force studio contact leaves off– once you have your credentials, everything here is yours to implement. If you are a studio admin setting up a Custom Cloud Automation Connector, see the Custom Cloud Automation Connector overview instead.

Getting Started

Prerequisites

Before you begin, your Creative Force studio contact will provide three values. Your application must store all three and allow each customer to configure their own set.

Client ID `String`	Used to identify your application when requesting an access token.
Client Secret `String`	Used alongside the Client ID in the OAuth token request.
Webhook Secret Key `String`	Used to verify that incoming webhook requests originated from Creative Force, not a third party.

The API base URL for all endpoints is https://gateway.creativeforce.io/v1. Full API reference documentation is available at developers.creativeforce.io.

Authorization

Client Credentials	Machine-to-machine (M2M) authorization. No user interaction required– the right fit for webhook sub-function integrations.
Authorization Code	User-to-application authorization. More granular user control, but a heavier implementation. Only needed when end-users must authorize individually.

See the API documentation for detailed setup: Getting started with Client Credentials Flow · Authorization Code Grant Flow.

Rate Limiting

The API enforces a limit of 20 requests per second per IP address.

Time Frame	Requests Allowed
1 second	20
1 minute	1,200
1 hour	72,000
1 day	1,728,000

⚠️ Implement Request Queue: Re-queuing 429 responses is not a safe strategy under burst conditions; it will compound the problem. A steady flow through a queue significantly increases throughput. The API documentation intro links to resources on rate limit handling.

Where Cloud Automation Sits in the Workflow

A Creative Force admin can place a Cloud Automation step at different points in a studio workflow. The two most common positions are:

Mode	Position in Workflow	Use Cases
Content Generation	Between Capture and Final Selection	Mannequin-to-on-model, still image to AI video, flat-to-ghost-mannequin
Post Production	After Final Selection	AI retouching, background removal, color correction, format conversion

Your integration does not need to detect which mode a workflow is in. Everything required to process and submit work is described per item in taskProcessExpectedOutputs, and returned by Get Process Detail.

Read each item's own flags rather than inferring behavior from the workflow configuration.

Integration Flow

Each task process follows the same 8-step cycle, from receiving a webhook event to submitting output back to Creative Force.

1	Listen for the Webhook Event	Receive a `ReadyToWork` event from Creative Force. Capture the `TaskProcessId` — required for every subsequent call.
2	Get Process Detail	Retrieve input assets, expected outputs, and style guide context for the task process.
3	Download Input Assets and Color References	Resolve asset and file IDs to pre-signed S3 download URLs, then download the files.
4	Get Additional Context (Optional)	Fetch product, job, outfit, or annotation data if your service needs the extra context.
5	Process the Assets	Run your external processing — AI generation, retouching, compositing, or conversion.
6	Update Process Status if Failed (If Applicable)	Signal failures back to Creative Force so tasks don't stall in progress.
7	Upload Output Files to Creative Force Storage	Get pre-signed S3 URLs, then PUT output files directly to Amazon S3.
8	Submit Output	Register uploaded assets against expected outputs. Creative Force advances the task when complete.

1. Listen for Webhook Event

Configure your endpoint to receive ReadyToWork events. Each Cloud Automation level emits the same event shape– filter by StepId to handle only the level(s) your integration is responsible for.

StepId Reference

Step Name	StepID	Notes
Cloud Automation	25	Default step
Cloud Automation (L1)	26	Level 1
Cloud Automation (L2)	27	Level 2
Cloud Automation (L3)	28	Level 3
Cloud Automation (L4)	29	Level 4
Cloud Automation (L5)	40	Level 5

Webhook Payload Example

Capture TaskProcessId immediately– it is required on every API call for the rest of this cycle.

JSON | ReadyToWork Event

{
  "Action": "ReadyToWork",
  "TaskId": "032b99a6-2de5-4545-b87a-336d4f7e861e",
  "TaskProcessId": "ee55d091-e7ca-4c5e-a38d-2e1ac7706a88",
  "SubfunctionId": 54,
  "SubFunctionName": "Mannequin to On Model",
  "JobId": "d84eef10-c8a6-437a-9f95-0b58d2a3cb38",
  "JobCode": "Summer 2026",
  "ClientId": "2c856b2f-aded-4609-bf67-27009603b2b9",
  "ClientName": "Acme Studio",
  "ProductId": "7a782d57-b0bf-4743-8f02-2b1a1e229869",
  "ProductCode": "AW2130146",
  "StepId": "25",
  "StepName": "Cloud Automation",
  "StepStatusId": "2000",
  "StepStatusName": "Ready To Work",
  "ShootingTypeId": "1",
  "ShootingTypeName": "AI On Model",
  "StyleGuideId": "2376b9cb-67db-490f-a5e8-89811ed6b087",
  "StyleGuideName": "Apparel: Pants and Skirts"
}

A rework event looks identical to a first pass ReadyToWork event — nothing in the webhook payload flags it as a rework. The process detail in Step 2 reveals the state via outputAssets and isRejected flags.

2. Get Process Detail

GET	`/v1/task-processes/{taskProcessId}/get-detail`

Returns the full context needed to process the task. The response has four key components:

Overview context: task, product, outfit, job, style guide, client, and step identifiers
Input assets: images/videos provided to this process, each with position and attribute
Output assets: assets produced by previous runs. Empty on a fresh run; populated on reject/rework cycles with isRejected flags
Expected outputs: one item per drop box to fill, with all flags and quantity rules your integration needs

Key Top-Level Fields

Field	Type	Description
`taskProcessId`	Guid	Use on all subsequent calls in this cycle.
`taskId`	Guid	Parent task identifier. Used for annotation fetches (Step 4).
`outfitId`	Guid	Populated when the product belongs to an outfit. Use to fetch styling assets for secondary products.
`clientId`	Guid	Owning workspace– required when requesting pre-signed upload URLs (Step 7a).
`colorReferenceFiles`	List<Guid>	File IDs for color reference images. Resolve via `bulk-get-files` (Step 3).
`inputAssets`	List	Assets provided to this process as input.
`outputAssets`	List	Assets from previous runs. Check `isRejected` to identify which need to be redone.
`taskProcessExpectedOutputs`	List	One item per drop box to fill. These drive how you structure your submission in Step 8.

Working with Expected Outputs

Each item in taskProcessExpectedOutputs represents one slot to fill. Read and act on each item's own flags — never infer behavior from the workflow configuration.

Field	Type	Description
`mappingKeyId`	string	Opaque slot identifier — treat it as a token. Use this exact value when submitting output in Step 8.
`isFreeMapping`	bool	`true` only in the pre-selection (free mapping) case. Submit all assets into this single slot without position mapping.
`isOptional`	bool	`false`: at least one asset is required. `true`: slot may be left empty, but any submitted assets must still satisfy quantity rules.
`minShots` / `maxShots`	int / int?	Min/max count for main + inclip + resource assets combined. `maxShots` may be `null` for unlimited.
`isAllowAlt`	bool	Whether alternate images are accepted for this slot.
`isEnforceAlts`	bool	Whether alternates are required.
`minShotsAlts` / `maxShotsAlts`	int	Min/max alternate count.
`isRejected`	bool	On a rework cycle, `true` means the entire drop box was rejected and must be replaced.
`outputAssetIds`	List<Guid>	Previous output asset IDs for this slot — needed when resubmitting on a rework cycle.
`assetContentTypeId`	enum	Expected media type: Photo (1) Video (2) Both (3)

Every mappingKeyId must appear in your Submit Output call– either with assets or with an empty assets array for optional slots you are not filling.

Omitting a mappingKeyId returns ErrorCode-1554: SubmitMappingKeyMismatch.

Enum Reference

EnumAssetAttribute
Value	Name
0	Normal
1	Inclip
2	Resource
4	Alternative
EnumAssetContentType
Value	Name
1	Photo
2	Video
4	Both

3. Download Input Assets & Color References

Use the IDs from Get Process Detail to fetch download URLs in bulk, then download the files from the returned pre-signed S3 URLs.

POST	`/v1/assets/bulk-get-assets`

Pass an array of assetId values from inputAssets. Returns each asset with its filename and a fileUrl pre-signed download URL.

POST	`/v1/assets/bulk-get-files`

Pass an array of fileId values from colorReferenceFiles (and any other file references, such as styling assets resolved in Step 4). Accepts up to 100 file IDs per request. Returns each file with its filename, URL, size, and MD5.

4. Get Additional Context

None of these calls are required to complete a task process. Use them only when your service needs the additional context.

Product & Job

GET	`/v1/jobs/{jobId}`
GET	`/v1/products/{productId}`

Annotations

(Most useful on rework cycles)

Returns reviewer annotations per asset– short text comments and optional markup images drawn over the asset in color. Use this to regenerate against specific reviewer feedback rather than guessing what to change.

GET	`/v1/tasks/{taskId}/annotation`

This endpoint is keyed by taskId, not taskProcessId. Each annotation can carry a markingFileId– resolve it via bulk-get-files to download the visual markup image.

Outfit Context

(when outfitId is populated)

An outfit groups a primary product with one or more secondary styling products– for example, a shirt (primary) paired with trousers and shoes (secondary). When your service needs to generate a complete styled look, use these endpoints to enumerate outfit products and retrieve their reference imagery.

GET	`/v1/outfits/{outfitId}/products`

Lists all products in the outfit (max 100). The roleId field distinguishes the primary product (1) from secondary styling products (2+).

POST	`/v1/products/styling-assets`

Returns the best available styling asset per (productId, positionTagId) for a list of products. Resolution follows shooting-type priority: Mannequin → Flat → non-OnModel → OnModel. Pass only the secondary products– the primary product's assets are already in inputAssets. The response returns fileId references; resolve them with bulk-get-files.

5. Process the Assets

Run your external processing on the downloaded input assets– AI-generated model replacement, ghost-mannequin compositing, retouching, background removal, color correction, format conversion, or whatever your service is responsible for. This is the work the integration exists to perform.

6. Update Process Status if Failed

If your service cannot complete processing– due to an upstream failure, invalid input, or an unrecoverable error– you must signal this back to Creative Force. Without this call, the task will sit indefinitely with a status of "In Progress" on the studio side.

PUT	`/v1/task-processes/{taskProcessId}/update-status`

See the API documentation for request body details and status values.

7. Upload Output Files to Creative Force Storage

Output files are uploaded to Amazon S3 using pre-signed URLs. This is a two-step process: first obtain the URLs, then upload directly to S3.

7a. Get Pre-signed URLs

POST	`/v1/assets/get-presigned-url`

Call this once per batch to mint pre-signed S3 PUT URLs for all output files in a single request. Assign a localId to each file so you can map the returned tempAssetId values back to your files.

{
  "clientId": "fe2bcb16-428f-4e21-9d8b-59ab0790eecd", //fromGetProcessDetail
  "physicalFileTypeId": 2,
  "files": [
    { "fileName": "output_front.jpg", "localId": "your-local-id-1", "fileLength": 2011193 },
    { "fileName": "output_back.jpg",  "localId": "your-local-id-2", "fileLength": 1982531 }
  ]
}

The response has three top-level fields:

`headers`	an array of `{key, value}` objects containing S3 encryption headers. These must be forwarded on every PUT in Step 7b. They apply to all files in the batch — do not look for encryption values on individual file entries.
`files`	one entry per requested file, each containing `presignedUrl`, `tempAssetId`, and `contentType`.
`errorFiles`	any files that failed to receive a URL (for example, invalid `fileName` or `fileLength`). Empty on a fully successful response.

Retain each file's tempAssetId (matched by localId) — required in Step 8.

tempAssetId values are single-use. If the same output file needs to be submitted to two different drop boxes, upload it twice and request a separate tempAssetId for each upload.

7b. Upload Files to S3

For each file, PUT the raw binary file contents to its presignedUrl. Set the following headers:

Every entry from the top-level headers array from 7a (S3 encryption headers– same for all files in the batch)
Content-Type set to the contentType value returned for that specific file

HTTP — S3 PUT request

PUT [presignedUrl]

x-amz-server-side-encryption: aws:kms
x-amz-server-side-encryption-aws-kms-key-id: arn:aws:kms:{region}:{account}:key/{key-id}
Content-Type: image/jpeg

[binary file contents]

Do not add any other headers or query parameters — all required query parameters are already baked into the pre-signed URL. A successful upload returns 200 OK with no body.

8. Submit Output

POST	`/v1/task-processes/{taskProcessId}/submit-output`

Assets are grouped by mappingKeyId, taken directly from taskProcessExpectedOutputs. Every mappingKeyId from Get Process Detail must appear, either with assets or with an empty assets array.

outputResultTypeId Values

Value	Name	When to Use	What `assetid` Should Be
1	ProcessNewAsset	A new asset generated in this run — the common case.	The `tempAssetId` from Step 7a.
2	KeepOldAsset	Rework cycle only — the asset was not rejected and should be retained as-is.	The previously submitted `outputAssetId`.
3	RedoAsset	Rework cycle only — replaces a rejected asset. Set `oldOutputAssetId` to the rejected output's ID.	The new `tempAssetId` from Step 7a.

Request Body Example

This example shows all three result types in a single submission. 1_Front receives a new main shot and a new alternate. 2_Back is a rework– the rejected output is replaced. 3_Detail is an optional slot with nothing to submit this run.

JSON | Submit Output Request

{
  "submitAssets": [
    {
      "mappingKeyId": "1_Front",
      "assets": [
        {
          // New main shot — assetId is the tempAssetId from Step 7a
          "oldOutputAssetId": null,
          "assetId": "4765ad06-6815-4980-a129-56520c0369b5",
          "outputResultTypeId": 1,
          "assetAttributeId": 0,   // Normal
          "resourceIds": null,
          "specId": null
        },
        {
          // Alternate shot — assetAttributeId 4 = Alternative
          "oldOutputAssetId": null,
          "assetId": "f641bfa0-e283-41d3-905a-568262e203ac",
          "outputResultTypeId": 1,
          "assetAttributeId": 4,   // Alternative
          "resourceIds": null,
          "specId": null
        }
      ]
    },
    {
      "mappingKeyId": "2_Back",
      "assets": [
        {
          // Rework — replace a rejected asset
          "oldOutputAssetId": "f29c1aa1-7a2d-40d8-b47f-9f72b36ae081",
          "assetId": "821ab78a-1667-4f86-9034-ccd685e6549c",
          "outputResultTypeId": 3,   // RedoAsset
          "assetAttributeId": 0,
          "resourceIds": null,
          "specId": null
        }
      ]
    },
    {
      // Optional slot — nothing to submit this run
      "mappingKeyId": "3_Detail",
      "assets": []
    }
  ]
}

Response

The response returns the final assetId and fileId for each submitted asset. Your integration should store these and map them back to your internal output records.

JSON | Response

{
  "assets": [
    { "assetId": "4765ad06-6815-4980-a129-56520c0369b5", "fileId": "3062ebd5-a4e8-4b7d-9e2b-02863ea13f34" },
    { "assetId": "f641bfa0-e283-41d3-905a-568262e203ac", "fileId": "3d40e0dc-b66c-4838-950e-71dd37811dd9" }
  ]
}

Once Submit Output completes successfully, Creative Force advances the task process to the next workflow step. No further API calls are needed from the external side for that task.

Rework Cycle

When a reviewer in Creative Force rejects outputs, Creative Force sends a fresh ReadyToWork webhook for the same task process. On the rework pass:

Check outputAssets in the Get Process Detail response — assets with isRejected: true need to be regenerated.
For each drop box (taskProcessExpectedOutputs item), check isRejected and outputAssetIds to determine which prior outputs to keep or replace.
When a drop box is partially rejected (some assets rejected, others not), re-submit the entire drop box. Use KeepOldAsset for non-rejected assets and RedoAsset for rejected ones.
Fetch annotations via Step 4 to give your service the reviewer's specific feedback before regenerating.

Amazon S3 Connector

External Post FTP: Vendor Guide

Dreem Connector

Dreem: Outfit Building

Custom Cloud Automation Connector

Custom Cloud Automation Connector: Vendor Guide