> This page is for Camera to Cloud.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# Instruções: Organizar ativos

## Introdução





Neste guia, aprenderemos como e até que ponto podemos controlar *onde* os ativos da sua integração são enviados.





## O que vou precisar?

Caso ainda não tenha lido o guia [Implementação do C2C: Configuração](./implementing-c2c-setting-up), dê uma olhada rápida nele antes de continuar! Você também precisará do `access_token` que recebeu durante o guia de autenticação e autorização do [hardware C2C](./implementing-c2c-authentication-and-authorization-hardware) ou do [aplicativo C2C](./implementing-c2c-authentication-and-authorization-c2c-application).

## Estrutura de pastas de ativos





Por padrão, os ativos são criados com a seguinte estrutura de pastas:

`Cloud Devices` > `{YYYY}_{MM}_{DD}` > `{ASSET_TYPE}` > `{YOUR_DEVICE}` > `{ASSET_NAME}` Onde `{ASSET_TYPE}` é `VIDEO`, `AUDIO` ou `DATA` (configurado para o modelo do seu dispositivo por canal), `{YOUR_DEVICE}` é o nome do dispositivo do projeto conectado ao projeto do usuário, e `{ASSET_NAME}` é o nome do recurso que você enviou e é o recurso que pode ser reproduzido no Frame.io.

### Roteamento de extensão

Você pode configurar seu dispositivo para direcionar diferentes recursos para pastas `{ASSET_TYPE}` personalizadas com base na extensão do arquivo em `{ASSET_NAME}`. Por exemplo, digamos que sua integração gere vários tipos diferentes de arquivos, cada um pertencente a uma proveniência específica. Você pode nos pedir para mapear esses ativos da seguinte forma:

```text
.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans
```





Agora, quando você criar o seguinte ativo:





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_codes]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "IMAGE_0001.jpeg", 
            "filetype": "image/jpeg", 
            "filesize": 21136250,
            "offset": 10
        }
__JSON__
} | python -m json.tool
```




<Info title="Especificação do ponto de acesso da API">
  A documentação para `/v2/assets` pode ser [encontrada aqui](/camera-to-cloud/api-reference/device-asset-create)
</Info>
 ... será encaminhado para um local como: `Cloud Devices` &gt; `2022_04_01` &gt; `STILLS` &gt; `MY_DEVICE` &gt; `IMAGE_0001.jpeg`. Se, em vez disso, o arquivo se chamasse `A001_C001.mov`, seria encaminhado para: `Cloud Devices` &gt; `2022_04_01` &gt; `VIDEO` &gt; `MY_DEVICE` &gt; `A001_C001.mov`.

### Caminhos de upload tokenizados

Algumas integrações podem precisar de maior controle sobre a estrutura de pastas criada pelo dispositivo. Por sua vez, nós, do [Frame.io](http://frame.io/), precisamos garantir que haja um certo nível de consistência na forma como os arquivos são enviados para o [Frame.io](http://frame.io/) a partir de um dispositivo C2C e, especificamente, oferecer garantias aos clientes do [Frame.io](http://frame.io/) sobre com qual parte de seus projetos um dispositivo C2C pode interagir. Com esse objetivo, permitimos que os integradores personalizem os locais de upload de ativos dentro da pasta `{YOUR_DEVICE}`, mas não permitimos que ativos sejam enviados fora dessa pasta.

Para fazer o upload para uma estrutura de pastas personalizada, você precisará entrar em contato com seu Gerente de parceiros. Estruturas de pastas personalizadas são um conjunto de metadados tokenizados que devem ser fornecidos na criação do ativo. Vamos ver um exemplo simples:

Digamos que temos uma articulação de câmera 3D que tem valores de `reel_name` como `&quot;A001&quot;`, `&quot;A002&quot;`, `&quot;A003&quot;`, etc. e valores de `clip_number` como `&quot;C001&quot;`, `&quot;C002&quot;`, etc. Queremos criar pastas para cada clipe e preenchê-las com os arquivos do olho esquerdo e do olho direito, de modo que os arquivos fiquem assim em um projeto: ![Caminho de pasta tokenizado — Exemplo de articulação 3D](/_fern-img/e40b09128d1cbf3c876fd14169a6406642d50d13ce7ab802baff4bbaf50bfd4a.webp)

Para isso, precisaremos definir duas configurações:




* Campos de metadados obrigatórios
* Caminho de arquivo tokenizado




Campos de metadados obrigatórios são uma lista simples de chaves que devem ser definidas na criação do ativo para sua integração:





```text
[reel_name, clip_number]
```

Você pode então usar qualquer uma dessas teclas para criar um caminho delimitado por `/`, utilizando `{field_name}` para indicar onde o valor de um campo deve ser inserido:

```text
REEL_{reel_name}/{reel_name}_{clip_number}
```

Ambas as configurações terão que ser fornecidas à nossa equipe no [Frame.io](http://frame.io/) para adicionar como parte dos detalhes da sua integração. Depois de configurarmos isso, quando você criar um ativo, esses valores terão que ser fornecidos na raiz do conteúdo para que a criação do ativo seja bem-sucedida:

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_LEFT.mp4", 
            "filetype": "video/mp4", 
            "filesize": 21136250,
            "offset": 10,
            "metadata": {
              "reel_name": "A001",
              "clip_number": "C001"
            },
        }
__JSON__
} | python -m json.tool
```

O exemplo acima criará um arquivo com um caminho completo como: `Cloud Devices` &gt; `2022_04_01` &gt; `VIDEO` &gt; `MY_DEVICE` &gt; `REEL_A001` &gt; `A001_C001` &gt; `A001_C001_LEFT.mp4`
<Error title="Erros de metadados">
  


Se o dispositivo não foi explicitamente configurado para permitir esses campos, você receberá um erro se tentar fazer a mesma chamada. Da mesma forma, se você configurar campos de metadados obrigatórios, DEVE fornecê-los no conteúdo de criação de ativo ou um erro será retornado.



</Error>


O conteúdo aceitará qualquer valor JSON válido. Valores que não são string são renderizados da seguinte forma:




* **integers**: renderizados na base 10: `10` -&gt; `&quot;10&quot;`
* **floats**: usa a representação mais curta de acordo com o algoritmo descrito em &quot;Como imprimir números de ponto flutuante com rapidez e precisão&quot; em Anais da Conferência SIGPLAN '96 sobre Projeto e Implementação de Linguagens de Programação.
* **booleans**: `true` e `false` são renderizados como `&quot;true&quot;` e `&quot;false&quot;`
* **null**: renderizado como uma string em branco. Se `reel_name` fosse definido como `null`, então a primeira pasta personalizada seria renderizada como `REEL_`




Em geral, sugerimos que você limite seus valores a strings e formate os demais valores como achar melhor (por exemplo, números inteiros sempre serão exibidos sem zeros à esquerda, algo que talvez você queira alterar).





Em geral, apenas campos que tenham um valor válido para todos os clipes devem ser usados. Se um campo nem sempre tiver um valor válido, você deve ter um plano para representar valores não definidos ou nulos.





## Empilhamento de versões

O [Frame.io](http://frame.io/) oferece suporte a [pilhas de versões](https://support.frame.io/en/articles/4431-version-stacking-and-comparison): uma maneira de agrupar várias iterações do mesmo conteúdo na interface do usuário. A API C2C permite que os dispositivos enviem novas iterações de um ativo, que serão incluídas em uma pilha de versões junto com suas versões anteriores. Para criar uma pilha de versões, você deve fornecer um `autoversion_id` para identificar a qual pilha de versões os ativos pertencem. Esse valor pode ser qualquer coisa: um UUID, um nome de arquivo, etc. Tome cuidado para usar apenas valores que nunca sejam repetidos acidentalmente em uma pasta de ativos. Por exemplo, se for possível que sua integração crie o mesmo nome de arquivo mais de uma vez, então o nome do arquivo *não* é uma boa opção para usar como `autoversion_id`.

Fornecemos um autoversion_id assim:





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v01.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 10,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```





Agora, sempre que você fizer upload de um novo ativo, se usar o mesmo autoversion_id, o ativo será adicionado como a versão mais recente em uma pilha com o ativo original:





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v02_with_color.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 10,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```





*Os ativos só serão empilhados se forem enviados para a mesma pasta*, então você precisa ter algumas coisas em mente se quiser implementar a pilha de versões:




* Os metadados tokenizados devem resolver para a mesma pasta principal para que a pilha de versões seja criada.
* Como a data de criação faz parte do caminho do arquivo, novas versões criadas após a meia-noite (UTC) podem não ser empilhadas corretamente, a menos que você forneça um deslocamento para a hora de criação do upload original.




Este segundo ponto é importante. Suponhamos que, 48 horas após o upload inicial, seja criada uma nova versão do ativo. Para que ela seja empilhada com o ativo original, devemos fornecer um deslocamento de 48 horas no passado: 172.800 segundos.





```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v03_with_color.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 172800,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```

Se o ativo atual *tivesse* sido enviado para `2022_04_03`, agora será enviado para `2022_04_01` e empilhado com o ativo correto.

## Próximas etapas





Este é o último guia para criar uma excelente integração C2C! Reserve um momento para se parabenizar! Talvez seja uma boa ideia fazer um lanchinho. A única coisa que resta fazer é revisar a lista de verificação do integrador, onde você encontrará um resumo de tudo o que é necessário para criar uma integração à prova de falhas.





Se ainda não o fez, recomendamos que entre em contato com nossa equipe e, em seguida, siga para o próximo guia. Estamos ansiosos para ter notícias suas!