Yapper Developer Docs

Starts a generation process and charges team credits. V1 types: image-generation, video-generation, image-upscale, video-upscale. The model must match the type (see GET /models). Always send an Idempotency-Key: retries with the same key and body return the original process instead of double-charging; the same key with a different body returns idempotency_conflict. input is validated per process type AND against the model's published capabilities (aspectRatios, resolutions, videoLengths from GET /models) — unsupported values are rejected with invalid_request, never silently coerced. Internal fields (batchId, filteringId, agent context) are ignored. metadata (flat string/number/boolean/null values, max 16 keys) is echoed back on reads. Optional webhookUrl receives a one-shot completion/failure notification.

Authorization

bearerAuth processes:write

AuthorizationBearer <token>

In: header

Scope: processes:write

Header Parameters

Idempotency-Key?string

Stable caller-provided key for retry-safe process creation.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*string

Value in

"image-generation"
"video-generation"
"image-upscale"
"video-upscale"

model*string

input*

Process-specific input, validated per process type. image-generation: prompt (string, required), aspectRatio (string), imageResolution (string), maskUrl (string), promptUpsampling (boolean), referenceImages ({docId, url}[]), referenceImageUrls (string[]). video-generation: prompt (string, required), aspectRatio (string), endingFrameImageUrl (string), referenceImages ({docId, url}[]), referenceVideos ({docId, url}[]), resolution (number), startingFrameImageUrl (string), videoLength (number). image-upscale: imageAssetDocId (string), imageUrl (string), upscaleFactor (number). video-upscale: prompt (string), upscaleFactor (number), videoAssetId (string), videoUrl (string). Model-specific limits (aspect ratios, resolutions, durations, reference counts) come from GET /models capabilities.

metadata?

Caller-owned metadata returned on process reads. Max 16 keys, 2 KB serialized.

webhookUrl?string

HTTPS URL notified once (best-effort, at-most-once) when the process reaches completed or failed. The payload is a thin notification { event, processId, status, creditsUsed, error?, metadata?, links } — fetch GET /processes/{processId} for the authoritative record.

Formaturi

dryRun?boolean

Validate the request and return a 200 DryRunEstimate (cost + whether it can start) without creating a process or charging credits. A successful dry run means the identical real request would start.

testMode?boolean

Development environments only: run against a local test provider, spending no credits.

Response Body

`application/json`

curl -X POST "https://example.com/processes" \  -H "Content-Type: application/json" \  -d '{    "type": "image-generation",    "model": "gpt-image-2",    "input": {      "prompt": "A polished product photo of a stainless steel water bottle",      "aspectRatio": "1:1",      "imageResolution": "1080"    },    "metadata": {      "externalId": "job_123",      "customerUserId": "user_456"    }  }'

{  "dryRun": true,  "type": "string",  "model": "string",  "creditsEstimated": 0,  "canStart": true,  "blockedBy": "team_limit",  "credits": {    "available": 0  },  "estimatedCompletionSeconds": 0}

{  "id": "string",  "type": "string",  "status": "queued",  "model": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "completedAt": "2019-08-24T14:15:22Z",  "estimatedCompletionSeconds": 0,  "creditsEstimated": 0,  "creditsUsed": 0,  "error": {    "code": "string",    "message": "string"  },  "input": {},  "outputs": [    {      "type": "image",      "assetId": "string",      "url": "http://example.com",      "width": 0,      "height": 0,      "duration": 0,      "mimeType": "string"    }  ],  "metadata": {    "property1": "string",    "property2": "string"  },  "links": {    "self": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`